Skip to main content
POST/crypto/federated-token

Get Federation Token

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
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
crypt *string

The crypt the token is for

op *"encrypt" | "decrypt" | "rewrap"

encrypt, or decrypt/rewrap (one class: decrypt)

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUEThe body is not exactly { crypt, op }, crypt does not match ^[a-z0-9-]{1,64}$, or op is not encrypt, decrypt or rewrap.
401K9O_UNAUTHENTICATEDThe caller is not authenticated.
401K9O_STEP_UP_REQUIREDA session's decrypt or rewrap token needs a fresh step-up for this crypt.
403K9O_EXTENSION_PERMISSION_DENIEDExtensions use k9o.kibo, not the crypto resource.
403K9O_ACCESS_DENIEDNot 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).
403K9O_IAM_POLICY_DENIEDThe caller may not use this crypt for this op.
403K9O_PAT_COLLECTION_NOT_PERMITTEDThe PAT is scoped to other crypts.
403K9O_RBAC_DENYEnd users cannot call the crypto resource.
404K9O_CRYPT_NOT_FOUNDAn encrypt token named a crypt that is not registered in this project.
409K9O_CUSTODY_SERVER_ROUTENo federated token for this project: route "server" (use the server route) or "client-idp" (use your own identity provider).
409K9O_KMS_FEDERATION_AUDIENCE_NOT_SETThe key attachment has no federation audience (GCP has no default): set it first.
409K9O_CRYPT_RETIREDAn encrypt token named a retired crypt. Decrypt and rewrap tokens still issue.
429K9O_RATE_LIMITEDToo many tokens for this project; retry after Retry-After.
503K9O_KEY_SERVICE_UNAVAILABLEThe key service could not issue a token (or federation is not configured in this region); nothing was issued.
Response body (200)
data *object

A short-lived identity token for your cloud's key service, and the values to check it against.

token *string

The signed identity token (RS256 JWT): present it to your cloud's token exchange

expiresAt *string <date-time>

At most 15 minutes after issuance

issuer *string

This project's issuer URL; it never changes

subject *string

<project>:crypt:<crypt>:op:<encrypt|decrypt>

audience *string

The audience set on your key attachment

kid *string

The id of the key that signed the token (kfk_...).

Your cloud finds it in the issuer's JWKS.

projectId *string

The project the token is for

provider *any

Your key attachment's cloud provider

One of: string
or: null
meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.crypto.federatedToken({
  crypt: 'payments',
  op: 'encrypt'
})

Showing example in TypeScript

Request example
{
  "crypt": "payments",
  "op": "encrypt"
}
Response example (200)
{
  "data": {
    "token": "string",
    "expiresAt": "string",
    "issuer": "string",
    "subject": "string",
    "audience": "string",
    "kid": "string",
    "projectId": "string",
    "provider": "string"
  }
}

More in Encryption