Token exchange involves exchanging an identity provider-signed token for a State Backed-signed token.

Token providers are responsible for creating State Backed tokens from a standardized claim set extracted from identity provider tokens by their mappings.

Token providers are identified by a service name. You might, for instance, want a service name for each application that you host with State Backed.

Token providers also specify the State Backed key to use to sign the tokens they generate and a mapping that creates the claims for the generated token.

For example, if your identity provider mappings extract claims like this:

{
  "sub": "your-sub",
  "email": "your-email",
  "provider": "identity-provider"
}

you could create a token provider like this:

curl -XPOST https://statebacked.dev/token-providers \
  -H 'authorization: Bearer sbsk_...'
  --data '{
    "keyId": "sbk_...", // ID for a previously-created State Backed key
    "service": "your-app", // any identifier for your token provider
    "mapping": {
      "sub.$": "$.sub",
      "email.$": "$.email",
      "provider.$": "$.provider",
    }
  }'

That token provider would allow you to exchange any of your identity provider- signed tokens for a State Backed token that includes the sub, email, and provider claims, all of which would be available for your use in allowRead and allowWrite functions in your machine definitions.

Upserts may change key ids and mappings.

This endpoint requires admin access.