Stitch SSO

5.7. Client Tokens

What are client tokens?

Most of the functionality of the Stitch API is protected by what is known as user tokens. User tokens represent a client's authorization to access certain features of the user's bank account.

In contrast, a client token is issued to a client by the API and represents the time limited ability to access certain features of the client's profile on the API.

A client token is issued when the client sends a client assertion to the token endpoint. To generate a client assertion, a confidential client is required.

Client Scopes

Scopes can be thought of as permissions to access certain features of the API.

If you attempt to make a request that needs extra scopes, the API response will return an error that lists the extra scopes required. The API documentation embedded in the IDE also includes the required scopes for different fields and mutations.

Client tokens have a different set of scopes than user tokens. The following scopes are currently available:

..

Client Scopes
Scope	Description
client_paymentrequest	The scope is required to create, view and manage payment requests.
client_bankaccountverification	The scope is required to submit bank account verification requests.
client_imageupload	This scope allows you to use the clientImageUpload endpoint
client_businesslookup	This scope allows you to lookup a business by name, registration number, or director identity / passport numbers.

In the next sections, we'll go through the steps needed to retrieve a client token with the client_paymentrequest scope.

Client Tokens

To proceed, you'll need a Client Id and Certificate. Stitch has sample test clients available that can access a simulated payment environment.

You'll also have needed to have generated a private_key_jwt from the certificate by following the steps in the confidential client guide.

Stitch uses the OAuth 2.0 Client Credentials Flow for client tokens. This flow entails making a POST request to the https://secure.stitch.money/connect/token endpoint with the following body parameters. The parameters are form encoded per OAuth 2.0 standards.

Token Request Body Parameters
Parameter	Description
client_id	This is a unique ID issued to you by a Stitch engineer
scope	A space separated list of requested scopes.
grant_type	Should be the value client_credentials for this flow
audience	Should always be the value https://secure.stitch.money/connect/token
client_assertion_type	Should always have the value urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion	The value of the generated private_key_jwt

Retrieving the Token Using cURL

This example bash script uses cURL to retrieve the access and refresh token.

You'll need to replace the clientId, clientSecret, and scopes with the appropriate values. This request if correctly formed, will return a JSON payload with the token.

1clientId='test-e2a28368-5431-4e7e-b6bd-dc45ac5dfa71'
2scopes='client_apicreditusage'
3clientAssertion='eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjgwNDE2MDQ5QzE0MjZDNDI0MzFGOERDMEUyRjUyQ0JEMDM1RjU1RUMifQ.eyJpYXQiOjE1OTg0NTQ0OTAsIm5iZiI6MTU5ODQ1NDQ5MCwiZXhwIjoxNTk4NDU0NzkwLCJhdWQiOiJodHRwczovL3NlY3VyZS5zdGl0Y2gubW9uZXkvY29ubmVjdC90b2tlbiIsImlzcyI6InRlc3QtZTJhMjgzNjgtNTQzMS00ZTdlLWI2YmQtZGM0NWFjNWRmYTcxIiwic3ViIjoidGVzdC1lMmEyODM2OC01NDMxLTRlN2UtYjZiZC1kYzQ1YWM1ZGZhNzEiLCJqdGkiOiJjMTZjMzAzMTcxMGI1MDk3ZDA5MmI3MmI3MGY1Yjc4NSJ9.tYFABuPfLXImaOPO8GszCijcnO3j91103JegFU2LORrXTp6EkreVKEuMmWGHxqbiFmY8m03WbFHb_thM6Vhe0pKkwHDktH7JaYvLoaEIy4R4Bj_obtJDRgEB1t1xsQGzyU4LigqVaRjoEPEOtf6LQeGYztiIPojzrKnnw8Dx404KCBGBp51L_VX_N410s3QgckYfMfjALXGkTgNYP-qvcSi4yV8tBTGaLYAbe65w1t8MNUCk9WGjT4zSHxySPIn7ILsBulVf75-Ro4SKU1Rhk9X534-NLHmgyR_syvXVwTQy_Z8PgHtihOCSSbrkrW-y-q2SFOEe5qmpKMEmQragNw'
4
5curl --location --request POST 'https://secure.stitch.money/connect/token' \
6--header 'Content-Type: application/x-www-form-urlencoded' \
7--data-urlencode 'grant_type=client_credentials' \
8--data-urlencode "client_id=$clientId" \
9--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
10--data-urlencode 'audience=https://secure.stitch.money/connect/token' \
11--data-urlencode "scope=$scopes" \
12--data-urlencode "client_assertion=$clientAssertion"

Retrieving the Token Using JavaScript and the Fetch API

1async function retrieveTokenUsingAuthorizationCode(clientId, clientSecret, scopes) {
2    const body = {
3        grant_type: 'client_credentials',
4        client_id: clientId,        
5        client_secret: clientSecret,        
6        scope: scopes.join(' '),
7        audience: 'https://secure.stitch.money/connect/token'
8    };
9
10    const bodyString = Object.entries(body).map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&');
11
12    const response = await fetch('https://secure.stitch.money/connect/token', {
13        method: 'post',
14        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
15        body: bodyString,
16    });
17
18    const responseBody = await response.json();
19    console.log('Tokens: ',  responseBody);
20    return responseBody;
21}

Retrieving the Token Using Postman

Download the following Postman collection, and import it into Postman:

StitchSSO_ClientCredentials.postman_collection.json

The first request in the collection is "Retrieve Client Token". Replace the entries in the Body tab with the appropriate values, and click send. The request if correctly formed will return a JSON payload with the token.

Response Body

A typical response body returned from the token endpoint will look like the following:

1{
2    "access_token": "udfc_WxDqxwfs5IKNHYohqGDZ9vwmyENvQYN7_cjW6M",
3    "expires_in": 3600,
4    "token_type": "Bearer",
5    "scope": "client_paymentrequest"
6}

Token Response Body Parameters
Parameter	Description
access_token	The token needed to query the Stitch API
expires_in	The number of seconds until the token expires
scope	The scopes that were granted by the user

We recommend that tokens are cached and only refreshed once expired as token generation is a cryptographically intensive process and so can slow down queries if retrieved on every request.

Using the confidential client to make API requests

Once you have obtained a token, you can use it to query the API in the same way that user tokens can. The short version is that you will need to include the token as the value in the Authorization header, prefixed with the string "Bearer ".

The Making API calls with the Access Token section of the SSO Intro goes into more detail.