# Get Federation Token

`POST /crypto/federated-token` · Core · Encryption

Issues a short-lived signed identity for the client-side crypto path on a project that uses your own key (BYOK or HYOK): present it to your cloud's token exchange (AWS AssumeRoleWithWebIdentity, GCP workload identity federation, Entra federated credentials) to wrap or unwrap with your key in your own process. The platform never sees the plaintext. Send `crypt` and `op` (`encrypt`, `decrypt` or `rewrap`).

The token is RS256, valid for at most 15 minutes, and carries:
- `iss`: this project's issuer URL, which never changes.
- `sub`: `<project>:crypt:<crypt>:op:<encrypt|decrypt>` (rewrap is decrypt).
- `aud`: the audience set on your key attachment; never taken from the request.
- `iat`, `exp`, `jti`, `k9o_project`, `k9o_crypt` and `k9o_op`.

It has no user id, email or name.

Who may ask is who may call the matching server route: decrypt and rewrap need a service token provisioned for the crypt, a crypto-scoped PAT naming it, a workload whose bound policy allows it, or a session with a fresh step-up. A project with a platform-managed key answers `409 K9O_CUSTODY_SERVER_ROUTE` with `route: "server"` (use the server route); a self-deployed project answers it with `route: "client-idp"` (federate with your own identity provider). Each issuance is audited.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `crypt` | string | yes | The crypt the token is for |
| `op` | enum ("encrypt", "decrypt", "rewrap") | yes | encrypt, or decrypt/rewrap (one class: decrypt) |

```json
{
  "crypt": "payments",
  "op": "encrypt"
}
```

## Responses

- **200**: Success

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes | A short-lived identity token for your cloud's key service, and the values to check it against. |
| `data.token` | string | yes | The signed identity token (RS256 JWT): present it to your cloud's token exchange |
| `data.expiresAt` | string (date-time) | yes | At most 15 minutes after issuance |
| `data.issuer` | string | yes | This project's issuer URL; it never changes |
| `data.subject` | string | yes | <project>:crypt:<crypt>:op:<encrypt\|decrypt> |
| `data.audience` | string | yes | The audience set on your key attachment |
| `data.kid` | string | yes | The id of the key that signed the token (`kfk_...`). Your cloud finds it in the issuer's JWKS. |
| `data.projectId` | string | yes | The project the token is for |
| `data.provider` | object | yes | Your key attachment's cloud provider |
| _one of_ | | |  |
| _or_ | | |  |
| `meta` | object | yes |  |


## Errors

| HTTP | Code | When |
|---|---|---|
| 400 | `K9O_INVALID_FIELD_VALUE` | The body is not exactly { crypt, op }, crypt does not match ^[a-z0-9-]{1,64}$, or op is not encrypt, decrypt or rewrap. |
| 401 | `K9O_UNAUTHENTICATED` | The caller is not authenticated. |
| 403 | `K9O_EXTENSION_PERMISSION_DENIED` | Extensions use k9o.kibo, not the crypto resource. |
| 401 | `K9O_STEP_UP_REQUIRED` | A session's decrypt or rewrap token needs a fresh step-up for this crypt. |
| 403 | `K9O_ACCESS_DENIED` | Not a member of this project (org roles do not grant access), an unscoped PAT asking for a decrypt token (reason crypto_requires_scoped_pat), or a service token not provisioned for the crypt (reason crypt_not_provisioned). |
| 403 | `K9O_IAM_POLICY_DENIED` | The caller may not use this crypt for this op. |
| 403 | `K9O_PAT_COLLECTION_NOT_PERMITTED` | The PAT is scoped to other crypts. |
| 403 | `K9O_RBAC_DENY` | End users cannot call the crypto resource. |
| 409 | `K9O_CUSTODY_SERVER_ROUTE` | No federated token for this project: route "server" (use the server route) or "client-idp" (use your own identity provider). |
| 409 | `K9O_KMS_FEDERATION_AUDIENCE_NOT_SET` | The key attachment has no federation audience (GCP has no default): set it first. |
| 429 | `K9O_RATE_LIMITED` | Too many tokens for this project; retry after Retry-After. |
| 503 | `K9O_KEY_SERVICE_UNAVAILABLE` | The key service could not issue a token (or federation is not configured in this region); nothing was issued. |
| 404 | `K9O_CRYPT_NOT_FOUND` | An encrypt token named a crypt that is not registered in this project. |
| 409 | `K9O_CRYPT_RETIRED` | An encrypt token named a retired crypt. Decrypt and rewrap tokens still issue. |

## Code samples

### cURL

```bash
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/crypto/federated-token' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "crypt": "payments",
  "op": "encrypt"
}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/crypto/federated-token', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "crypt": "payments",
  "op": "encrypt"
}),
});
const { data, meta } = await res.json();
```

### k9o CLI

```bash
k9o crypto federated-token --crypt <crypt>
```

### @k9o/core

```typescript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.crypto.federatedToken({
  crypt: 'payments',
  op: 'encrypt'
})
```

### k9o

```python
# k9o = create_client(org_slug="playground", project_slug="storefront", api_key="k9o_…")
response = k9o.crypto.federated_token({
    "crypt": "payments",
    "op": "encrypt"
})
```

### sdk-go

```go
// ctx := context.Background()
// client, _ := k9o.NewClient(k9o.ClientOpts{OrgSlug: "playground", ProjectSlug: "storefront", APIKey: "k9o_…"})
data, _, kerr := client.Crypto.FederatedToken(ctx, map[string]any{"crypt": "payments", "op": "encrypt"})
```

### k9o

```rust
// let k9o = Client::new(ClientOpts { org_slug: "playground".into(), project_slug: "storefront".into(), api_key: "k9o_…".into() })?;
let resp = k9o.crypto.federated_token(json!({"crypt": "payments", "op": "encrypt"})).await?
```

### dev.k9o:core

```java
// K9o k9o = K9o.createClient(K9o.Opts.builder().orgSlug("playground").projectSlug("storefront").apiKey("k9o_…").build());
var response = k9o.crypto().federatedToken(Map.of("crypt", "payments", "op", "encrypt"))
```

### K9o.Core

```c#
// var k9o = K9oClient.Create(new K9oOptions { OrgSlug = "playground", ProjectSlug = "storefront", ApiKey = "k9o_…" });
var response = await k9o.Crypto.FederatedTokenAsync(new Dictionary<string, object> { ["crypt"] = "payments", ["op"] = "encrypt" })
```

### k9o

```ruby
# k9o = K9o.create_client(org_slug: "playground", project_slug: "storefront", api_key: "k9o_…")
response = k9o.crypto.federated_token({ crypt: "payments", op: "encrypt" })
```

### k9o/sdk

```php
// $k9o = K9oClient::create(['org_slug' => 'playground', 'project_slug' => 'storefront', 'api_key' => 'k9o_…']);
$response = $k9o->crypto->federated_token(['crypt' => 'payments', 'op' => 'encrypt'])
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/get-federation-token
