Skip to content

Consume internal API on behalf of a citizen

This how-to guides you through the steps required to consume an API secured with TokenX:

  1. Configure your application
  2. Exchange token with TokenX
  3. Consume the API using the token


Configure your application

Enable TokenX in your application:

    enabled: true

Depending on how you communicate with the API you're consuming, configure the appropriate outbound access policies.

Exchange token

Create client assertion

To perform a token exchange, your application must authenticate itself. To do so, create a client assertion.

Sign the client assertion with your applications private key contained within the TOKEN_X_PRIVATE_JWK environment variable.

The assertion must contain the following claims:

Claim Example Value Description
sub dev-gcp:my-team:app-a The subject of the token. Set to the TOKEN_X_CLIENT_ID environment variable.
iss dev-gcp:my-team:app-a The issuer of the token. Set to the TOKEN_X_CLIENT_ID environment variable.
aud The audience of the token. Set to the TOKEN_X_TOKEN_ENDPOINT environment variable.
jti 83c580a6-b479-426d-876b-267aa9848e2f The JWT ID of the token. Used to uniquely identify a token. Set this to a UUID or similar.
nbf 1597783152 nbf stands for not before. Set to now.
iat 1597783152 iat stands for issued at. Set to now.
exp 1597783182 exp is the expiration time of the token. Between 1 and 120 seconds after now. Typically 30 seconds is fine.

Additionally, the headers of the assertion must contain the following parameters:

Parameter Value Description
kid 93ad09a5-70bc-4858-bd26-5ff4a0c5f73f The key identifier of the key used to sign the assertion. This identifier is available in the JWK found in TOKEN_X_PRIVATE_JWK.
typ JWT Represents the type of this JWT. Set this to JWT.
alg RS256 Represents the cryptographic algorithm used to secure the JWT. Set this to RS256.
Example Client Assertion Values
  "kid": "93ad09a5-70bc-4858-bd26-5ff4a0c5f73f",
  "typ": "JWT",
  "alg": "RS256"
  "sub": "prod-gcp:namespace-gcp:gcp-app",
  "aud": "",
  "nbf": 1592508050,
  "iss": "prod-gcp:namespace-gcp:gcp-app",
  "exp": 1592508171,
  "iat": 1592508050,
  "jti": "fd9717d3-6889-4b22-89b8-2626332abf14"

Create and perform exchange request

Now that you have a client assertion, we can use this to exchange the inbound token you received from your consumer.

Create a POST request with the following required parameters:

Parameter Value Comment
grant_type urn:ietf:params:oauth:grant-type:token-exchange
client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion The client assertion. Token that authenticates your application. It should be unique and only used once.
subject_token_type urn:ietf:params:oauth:token-type:jwt
subject_token The inbound citizen token, either from ID-porten or TokenX Token that should be exchanged.
audience The identifier for the target application Value follows naming scheme <cluster>:<namespace>:<appname>, e.g. prod-gcp:namespace1:app1

Send the request to the token_endpoint, i.e. the URL found in the TOKEN_X_TOKEN_ENDPOINT environment variable.

Example request
Content-Type: application/x-www-form-urlencoded


Success response

TokenX responds with a JSON object that contains the new access token:

Success response body
  "access_token" : "eyJraWQiOi..............",
  "expires_in" : 899,

Your application does not need to validate this token.

Cache your tokens

The expires_in field in the response indicates the lifetime of the token in seconds.

Use this field to cache and reuse the token to minimize network latency impact.

A safe cache key is key = sha256($subject_token + $audience).

Error response

If the exchange request is invalid, you will receive a structured error as specified in RFC 8693, Section 2.2.2:

Error response body
  "error_description" : "token exchange audience <some-audience> is invalid",
  "error" : "invalid_request"

Consume API

Once you have acquired the token, you can finally consume the target API.

Use the token in the Authorization header as a Bearer token:

GET /resource HTTP/1.1

Authorization: Bearer eyJraWQ...