# Request a new token

> Management API · Your Profile

```http
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` header — Bearer authentication of the form `Bearer <token>`.

## Request body

Content type: `application/json`

- `description` · string · Optional · _0-128 characters_ — Description of the token. Max 128 characters.
- `expireDate` · string · Optional · _format: date-time_ — Token expiration date. Maximum one year after creation.
- `organizationId` · string · **Required** · _format: uuid_ — ID of the organization that this token allows access to.
- `permissions` · map from strings to any · Optional — Token permissions. Only needed if the `type` is one of '('restricted', 'ephemeral')'.
  - `[any key]` · any — map of additional properties
- `type` · enum · **Required** — Type of token.
  - Allowed values: `login`, `full-access`, `restricted`, `ephemeral`

## Example request

```bash
curl -X POST "https://app.mk.io/api/v1/user/tokens" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Development token for my home machine",
  "expireDate": "2024-01-01T00:00:00Z",
  "organizationId": "00000000-0000-0000-0000-000000000000",
  "permissions": {},
  "type": "full-access"
}'
```

## Responses

### 201 — Created

- `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** · _format: uuid_ — ID of token.
  - `type` · enum · **Required** — Token type.
    - Allowed values: `login`, `full-access`, `restricted`, `ephemeral`
- `spec` · object · **Required** — Token spec.
  - `description` · string · Optional · _0-128 characters_ — Description of the token. Max 128 characters.
  - `expires` · string · **Required** · _format: date-time_ — Date token expires.
  - `issued` · string · **Required** · _format: date-time_ — Date token was issued.
  - `lastUsed` · string or null · **Required** · _format: date_ — Date token was last used on the MK.IO api.
  - `organizationId` · string or null · Optional · _format: uuid_ — ID of the organization that this token allows access to.
  - `permissions` · map from strings to any · Optional — The RBAC capabilities assigned to the token when type is 'restricted'
    - `[any key]` · any — map of additional properties
  - `revoked` · string or null · **Required** · _format: date-time_ — 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.

Example:

```json
{
  "kind": "string",
  "metadata": {
    "JWT": "string",
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "full-access"
  },
  "spec": {
    "description": "string",
    "expires": "2024-01-01T00:00:00Z",
    "issued": "2024-01-01T00:00:00Z",
    "lastUsed": "2024-01-01",
    "organizationId": "00000000-0000-0000-0000-000000000000",
    "permissions": {},
    "revoked": "2024-01-01T00:00:00Z",
    "revokedBy": "string",
    "user": "string"
  }
}
```

### 400 — Bad Request

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 401 — Unauthorized

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 403 — Forbidden

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 404 — Not Found

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 429 — Too Many Requests

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

### 500 — Internal Server Error

- `error` · object · **Required** — Pertinent information about the error
  - `code` · string · **Required** — The error code.
  - `detail` · string · **Required** — The error message.
  - `extraDetail` · map from strings to any · Optional — Extra information regarding this error.
    - `[any key]` · any — map of additional properties
- `ref` · string · **Required** — A reference to the request that caused the error.
- `status` · integer · **Required** — The HTTP status code

Example:

```json
{
  "error": {
    "code": "string",
    "detail": "string",
    "extraDetail": {
      "key": null
    }
  },
  "ref": "string",
  "status": 0
}
```

---

Source spec: `management-api` · operationId: `[post]_/api/v1/user/tokens`