Request a new token

post https://app.mk.io/api/v1/user/tokens

Request a new token granting access to the MK.IO API. There are four types of tokens.

  • 'restricted' tokens can have an expireDate set to up to a year in the future grant a reduced set of capabilities. Please see our online documentation for a description of how the capabilities are defined.
  • 'login' tokens are short-lived and grant the full user capabilities.
  • 'full-access' tokens can have an expireDate set to up to a year in the future and grant the full user capabilities.
  • 'ephemeral' tokens are short-lived and grant a reduced set of capabilities, similar to 'restricted' tokens.

Where possible you should prefer 'restricted' tokens over 'full-access' tokens to reduce the impact if one is exposed accidentally.

An API token allows access to MK.IO to anyone who has a copy of it - you should treat these like your car keys and keep them safe.

Authentication

Authorization Bearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

descriptionstringOptional0-128 characters
Description of the token. Max 128 characters.
expireDatestringOptionalformat: date-time
Token expiration date. Maximum one year after creation.
organizationIdstringRequiredformat: uuid
ID of the organization that this token allows access to.
permissionsmap from strings to anyOptional
Token permissions. Only needed if the type is one of '('restricted', 'ephemeral')'.
Show value schemaHide value schema
[any key]any
typeenumRequired
Type of token.
Allowed values:loginfull-accessrestrictedephemeral

Response

201 Created
kindstringOptional
The kind of record.
metadataobjectUserTokenMetadataSchemaRequired
Token metadata.
Show 3 propertiesHide 3 properties
JWTstringOptional
Generated token. We do not store this token, so you will not be able to see it again. Please copy it and keep it securely.
idstringRequiredformat: uuid
ID of token.
typeenumRequired
Token type.
Allowed values:loginfull-accessrestrictedephemeral
specobjectUserTokenSpecSchemaRequired
Token spec.
Show 9 propertiesHide 9 properties
descriptionstringOptional0-128 characters
Description of the token. Max 128 characters.
expiresstringRequiredformat: date-time
Date token expires.
issuedstringRequiredformat: date-time
Date token was issued.
lastUsedstring or nullRequiredformat: date
Date token was last used on the MK.IO api.
organizationIdstring or nullOptionalformat: uuid
ID of the organization that this token allows access to.
permissionsmap from strings to anyOptional
The RBAC capabilities assigned to the token when type is 'restricted'
Show value schemaHide value schema
[any key]any
revokedstring or nullRequiredformat: date-time
Date token was revoked, or null if not revoked.
revokedBystringOptional
Email of user who revoked this token.
userstringRequired
Email of user the token was issued for.

Errors

400 Bad Request
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
401 Unauthorized
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
403 Forbidden
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
404 Not Found
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
429 Too Many Requests
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
500 Internal Server Error
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code