Client AuthenticationDeprecated

caution

This section includes information around Stitch products and features that are now deprecated. Deprecated aspects of Stitch's plaform are no longer being supported or improved upon.

If you are currently using a deprecated Stitch product, please consider upgrading to one of our newer and equivalent offerings.

To initiate the process of creating a payment authorization request, a client token having the scope client_paymentauthorizationrequest is required. This scope allows you to create URLs to link a user's bank account for user-not-present payments.

Retrieving a Client Token

Stitch uses the OAuth 2.0 Client Credentials Flow for client tokens. This flow entails making a POST request to the endpoint https://secure.stitch.money/connect/token. The table below lists the required body parameters.

Note that all the parameters are required and should be 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

Retrieving the Token Using Postman

To quickly 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.

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;
}

Response Body

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

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

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 the access token is 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.