Upsert a token provider

POST /token-providers

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.

application/json

Body

Token provider configuration

  • keyId string Required

    ID of the State Backed key (created using smply keys create or posting to /keys) to use to sign tokens created by this token provider.

  • service string Required

    The name of this token provider. This name is used to request tokens from the /tokens endpoint

    Format should match the following pattern: ^[a-zA-Z0-9_-]{1,128}$.

  • mapping object Required

    A mapping object that creates the claim set for the State Backed token and may reference the claims extracted by the identity provider mappings.

    The values of properties that end in ".$" are treated as JSONPath references into the claim set of the provided token.

    So a mapping of { "sub.$": "$.sub" } with identity provider claims of { "sub": "user-123" } will result in { "sub": "user-123" } as the State Backed token claims.

    Hide mapping attribute Show mapping attribute

Responses

  • 204

    The token provider was created or updated.

POST /token-providers
curl \
 -X POST https://api.statebacked.dev/token-providers \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"keyId":"string","service":"string","mapping":{}}'
Request example
{
  "keyId": "string",
  "service": "string",
  "mapping": {}
}