---
title: "Derive Token"
method: POST
path: "/v2alpha1/admin/apiKeys:derive"
tags: ["ApiKeys"]
---

# Derive Token

`POST /v2alpha1/admin/apiKeys:derive`

Mints a short-lived JWT or Macaroon token from an API key. Works with both
issued and imported keys. The derived token inherits the permissions of the
parent API key.

```http
POST /v2alpha1/admin/apiKeys:derive
{
  "credential": "eyJhbGciOiJFZERTQSI...",
  "ttl": "1h"
}
```

## Request body

- DeriveTokenRequest
  - `algorithm` 'TOKEN_ALGORITHM_UNSPECIFIED' | 'TOKEN_ALGORITHM_JWT' | 'TOKEN_ALGORITHM_MACAROON' — - TOKEN_ALGORITHM_JWT: JWT with EdDSA (self-contained, signed) - TOKEN_ALGORITHM_MACAROON: Macaroon with HMAC (self-contained, caveat-based)
  - `credential` string
  - `custom_claims` object — custom_claims is a JSON object whose entries are merged into the JWT payload (or macaroon caveats) at signing time. Reserved JWT claims (iss, sub, aud, exp, nbf, iat, jti) are rejected. Total serialized size is capped at 4KB.
  - `scopes` string[]
  - `ttl` string — ttl sets the expiry as a duration from now. Encoded as a google.protobuf.Duration (string ending in "s", e.g. "3600s"). Accepted bounds: 1s to 315360000s (~10 years). If unset or zero, the project default TTL applies. For convenience, the server also accepts Go-style duration strings ("24h", "30m", "1h30m") and an extended unit set ("1d", "1w", "1mo", "1y"; approximations: 1mo = 30d, 1y = 365d). Clients should prefer the standard Duration encoding for portability.

## Response `200`

A successful response.

- DeriveTokenResponse
  - `token` Token
    - `claims` object — claims is the decoded token payload. For JWT, this contains the standard claims (iss, sub, aud, exp, iat, jti) plus custom claims. For macaroons, this lists the caveats. The shape is backend-dependent and should be treated as opaque diagnostic data.
    - `expire_time` string, date-time
    - `scopes` string[]
    - `token` string — The encoded token string. JWT tokens are signed JWS in compact serialization (header.payload.signature). Macaroons are base64-encoded binary blobs.

## Other responses

- `default` — An unexpected error response.

---

[API](https://skmtc.net/ory/apis/ory-talos-api.md) · [All operations](https://skmtc.net/ory/apis/ory-talos-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ory/ory-talos-api/versions/faeb5ce56780/schema)