Client Tokens

What are Client Tokens?

While user tokens represent a client's authorization to access certain features of a user's bank account, a client token represents the time-limited ability to access certain features of the client's profile on the API.

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:

Scope	Description
client_paymentrequest	This scope is required to create, view and manage Pay By Bank payment requests.
client_bankaccountverification	This 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.
client_paymentauthorizationrequest	This scope allows you to create URLs to link user's accounts for LinkPay payment requests.
client_refund	This scope allows you issue refunds for a payment made with Stitch.
client_disbursement	This scope allows you to issue a disbursement: An instruction to Stitch to pay money out to a destination account.
client_recurringpaymentconsentrequest	This scope allows you to create a recurring payment : An instruction to Stitch to collect funds from your customer on their behalf, on a recurring basis, by creating a debicheck mandate

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

Retrieving a Client Token

To proceed, you'll need a client_id and client_secret.

For secret-based auth you will need make use of your client_secret by following the steps in the client secrets 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. The table below lists the required body parameters. The parameters are form encoded per OAuth 2.0 standards.

Request Parameter	Description
client_id	This is the unique ID of the client you generated
scope	A non-empty, 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_secret	The value of your client_secret

The API URL https://secure.stitch.money/connect/token can be used for all client token retrievals (whether on test or live clients).

Retrieving the Token Using cURL

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

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

clientId='<your clientId>'
scopes='client_paymentrequest'
clientSecret='<your client secret>'

curl --location --request POST 'https://secure.stitch.money/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode "client_id=$clientId" \
--data-urlencode 'audience=https://secure.stitch.money/connect/token' \
--data-urlencode "scope=$scopes" \
--data-urlencode "client_secret=$clientSecret"

Retrieving the Token Using JavaScript and the Fetch API

The example Javascript function below uses fetch to retrieve the client access token. You'll need to pass in appropriate values for clientId, clientSecret, and scopes to the function retrieveTokenUsingClientSecret

async function retrieveTokenUsingClientSecret(clientId, clientSecret, scopes) {
  const body = {
    grant_type: "client_credentials",
    client_id: clientId,
    scope: scopes.join(" "),
    audience: "https://secure.stitch.money/connect/token",
    client_secret: clientSecret,
  };

  const bodyString = Object.entries(body)
    .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
    .join("&");

  const response = await fetch("https://secure.stitch.money/connect/token", {
    method: "post",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: bodyString,
  });

  const responseBody = await response.json();
  console.log("Tokens: ", responseBody);
  return responseBody;
}

Retrieving the Token Using Postman

To test this out easily on Postman, import the collection available here into your Postman client.

The request we're using in the collection is Retrieve Client Token. Replace the entries for client_id and client_secret in the collection's Body tab with appropriate values matching your client details, and click send. If constructed correctly, the request will return a JSON payload with the token.

Response Body

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

{
  "access_token": "udfc_WxDqxwfs5IKNHYohqGDZ9vwmyENvQYN7_cjW6M",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "client_paymentrequest"
}

Response 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. More information about client token lifetimes can be found here.

Making API Requests with a Client Access Token

Now that you have a client access token, try it out by initiating a Payment Request or performing a Bank Account Verification.