> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://mediakind.ferndocs.com/platform/how-to/management/tokens/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mediakind.ferndocs.com/_mcp/server.

# Tokens

Tokens authenticate applications to the MK.IO APIs. The Management API gives you two views: user-level management for your own tokens, and organization-level management for auditing or revoking tokens across the organization. A token never grants more than the user who created it has, so the main decision is how much of that access to expose.

## Choosing a token type

There are four types. For automation, prefer `restricted` so an exposed token cannot do more than its job requires.

| Type          | Capabilities                 | Expiry                   |
| ------------- | ---------------------------- | ------------------------ |
| `login`       | Full user capabilities       | Short-lived              |
| `full-access` | Full user capabilities       | Optional, up to one year |
| `restricted`  | A scoped subset you define   | Optional, up to one year |
| `ephemeral`   | A scoped subset, short-lived | Short-lived              |

## Create a full-access token

A token is created with `POST`. `type` and `organizationId` are always required.

* Terminal window

```bash
curl -X POST "https://app.mk.io/api/v1/user/tokens" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "full-access",
    "description": "CI deployment token",
    "organizationId": "<ORG_ID>",
    "expireDate": "2027-01-01T00:00:00Z"
  }'

```

The response includes the generated token as `metadata.JWT`. MK.IO does not store it, so it is visible only at creation time, for five minutes. Copy it somewhere secure immediately.

## Create a restricted token

A `restricted` token adds a `permissions` object that must be a strict subset of your own capabilities. Read your access first so you know what you can grant:

```bash
curl -X GET "https://app.mk.io/api/v1/user/rbac" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

Then build `permissions` from a subset of that structure. This example grants only asset operations on one project:

```bash
curl -X POST "https://app.mk.io/api/v1/user/tokens" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "restricted",
    "description": "Asset automation, one project",
    "organizationId": "<ORG_ID>",
    "expireDate": "2027-01-01T00:00:00Z",
    "permissions": {
      "core.project": {
        "<PROJECT_ID>": {
          "ams.asset": ["create", "delete", "get", "update"]
        }
      }
    }
  }'

```

## Inspect and revoke

List or read your own tokens. Expired tokens are filtered out of the list.

```bash
curl -X GET "https://app.mk.io/api/v1/user/tokens" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

A token record carries operational fields including `issued`, `expires`, `lastUsed`, `revoked`, and (for restricted tokens) `permissions`. Revoke one token, or all of your tokens at once:

```bash
curl -X DELETE "https://app.mk.io/api/v1/user/tokens/<TOKEN_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

```bash
curl -X DELETE "https://app.mk.io/api/v1/user/tokens" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

Use the revoke-all carefully: it affects all of your tokens across organizations.

## Audit tokens across the organization

An organization admin can list every token with access to the organization, and revoke any of them:

```bash
curl -X GET "https://app.mk.io/api/v1/organization/tokens" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

curl -X DELETE "https://app.mk.io/api/v1/organization/tokens/<TOKEN_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

## What goes wrong

The token is lost after creation. The `JWT` is shown once, for five minutes, and is never stored. If you miss it, revoke the token and create a new one.

* A restricted token returns `403`. Its `permissions` must be a subset of your own access. Compare against `/api/v1/user/rbac`, and remember the token loses capabilities if your own access is later reduced.

* Forgetting the expiry ceiling. `expireDate` cannot be more than one year after creation.

## What comes next

* Users and teams: the access model a token’s permissions draw from.

* Authentication and tokens: bearer-auth basics and UI-based personal token creation.