Token Exchange

This page describes how to request a token exchange. These authentication tokens should be used when making api requests for a single user.

Scopes

ScopeUse
api:readUsed to perform read-only operations for machine to machine (M2M) scenrarios.
api:writeUsed to perform full CRUD operations for machine to machine (M2M) scenrarios.
ui:client-onboardingUsed for the Onboarding Client Component
api:credit-insights:readAccess to Read Credit Insights data
api:profile:readAccess to Read Profile data
api:trade-line:readAccess to Read Credit Line data
consumer:<upwardli_consumer_id>Access to Read and Write data for a specific consumer

Exchanging Tokens Using The API

Once a valid token has been obtained using the Authentication API, a limited scope token can be obtained using the token exchange API. This token can be used to make requests for a specific consumer, and is safe to send to the client application/web browser as needed.

To request a token exchange send a POST to our auth server containing the access_token and requested scope.

Token Exchange Request

POST https://auth-sandbox.upwardli.com/auth/token/exchange/

1Header
2{
3    "Authorization":"Bearer [access_token]"
4}
5Body
6{
7    "grant_type":"urn:ietf:params:oauth:grant-type:token-exchange",
8    "subject_token_type":"urn:ietf:params:oauth:token-type:access_token",
9    "subject_token":"[access_token]",
10    "audience":"https://auth-sandbox.upwardli.com",
11    "scope":"api:credit-insights:read api:profile:read api:write consumer:[upwardli_consumer_id]"
12}

Here’s what a successful response looks like:

1{
2    "token_type": "Bearer",
3    "expires_in": 3600,
4    "access_token": "[scoped access token]",
5    "scope": "api:credit-insights:read api:profile:read api:write",
6    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
7}

Notes:

  • The audience must be for the correct Environment.
  • The upwardli_consumer_id is the Upwardli id that you get from the Consumer.created webhook.
  • The new access token is a significantly longer string than the original access token.