# 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.

Requires authentication; no additional RBAC permissions required.

## Authentication

Authorization Bearer

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

## Request

This endpoint expects an object.

| Field               | Type      | Required | Description                                                   |
|---------------------|-----------|----------|---------------------------------------------------------------|
| description         | string    | Optional | Description of the token. Max 128 characters.                |
| expireDate          | string    | Optional | Token expiration date. Maximum one year after creation.      |
| organizationId      | string    | Required | ID of the organization that this token allows access to.     |
| permissions         | map       | Optional | Token permissions. Only needed if the `type` is one of ('restricted', 'ephemeral'). |
| type                | enum      | Required | Type of token. Allowed values: login, full-access, restricted, ephemeral. |

## Response

201 Created

| Field               | Type       | Required | Description                                                   |
|---------------------|------------|----------|---------------------------------------------------------------|
| kind                | string     | Optional | The kind of record.                                          |
| metadata            | object     | Required | Token metadata.                                             |
| JWT                 | string     | Optional | 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. |
| id                  | string     | Required | ID of token.                                               |
| type                | enum       | Required | Token type. Allowed values: login, full-access, restricted, ephemeral. |
| spec                | object     | Required | Token spec.                                               |

| Field               | Type      | Required | Description                                                   |
|---------------------|-----------|----------|---------------------------------------------------------------|
| description         | string    | Optional | Description of the token. Max 128 characters.                |
| expires             | string    | Required | Date token expires.                                          |
| issued              | string    | Required | Date token was issued.                                      |
| lastUsed            | string or null | Required | Date token was last used on the MK.IO api.              |
| organizationId      | string or null | Optional | ID of the organization that this token allows access to.   |
| permissions         | map       | Optional | The RBAC capabilities assigned to the token when type is 'restricted'. |
| revoked             | string or null | Required | Date token was revoked, or null if not revoked.             |
| revokedBy           | string    | Optional | Email of user who revoked this token.                        |
| user                | string    | Required | Email of user the token was issued for.                     |

## Errors

### 400 Bad Request

| Field               | Type      | Required | Description                                                   |
|---------------------|-----------|----------|---------------------------------------------------------------|
| code                | string    | Required | The error code.                                           |
| detail              | string    | Required | The error message.                                        |
| extraDetail         | map       | Optional | Extra information regarding this error.                     |
| ref                 | string    | Required | A reference to the request that caused the error.          |
| status              | integer   | Required | The HTTP status code.                                      |

### 401 Unauthorized

### 403 Forbidden

### 404 Not Found

### 429 Too Many Requests

### 500 Internal Server Error

| Field               | Type      | Required | Description                                                   |
|---------------------|-----------|----------|---------------------------------------------------------------|
| code                | string    | Required | The error code.                                           |
| detail              | string    | Required | The error message.                                        |
| extraDetail         | map       | Optional | Extra information regarding this error.                     |
| ref                 | string    | Required | A reference to the request that caused the error.          |
| status              | integer   | Required | The HTTP status code.