Stitch Partner API Authentication Guide

Stitch authenticates API requests using an API access token. As an API client, you’ll need to obtain an API access token before you can make API requests on behalf of a user’s Stitch client account. In this guide, we’ll cover the available methods for obtaining an access token and authenticating to the API.

For more info about API access tokens, refer to the API reference.

• Generate tokens for a new Stitch account with the API

• Generate tokens and authenticate using OAuth2

• Next steps

Prerequisites

• Stitch partner credentials. To use the Stitch API as a partner, complete this form. Once approved, you’ll receive the credentials required to authenticate requests made from your API client.

Generate tokens for a new Stitch account with the API

This approach will create a new Stitch client account using the API. When a new Stitch client account is successfully created, the response will include an access token, which you can use to authenticate API calls to other endpoints:

• Step 1: Create a Stitch account and generate a token

• Step 2: Authenticate your API requests

Step 1: Create a Stitch account and generate a token

Using your API client credentials, create a new Stitch client account using the Create Account endpoint.

In the body of the request, include your partner_id and partner_secret, along with the other properties required to create a Stitch client account:

curl -X POST https://api.stitchdata.com/v3/accounts
     -H 'Content-Type: application/json'
     -d "{
          "partner_id": "<YOUR_PARTNER_ID>",
          "partner_secret": "<YOUR_PARTNER_SECRET>",
          "first_name": "<USER'S_FIRST_NAME>",
          "last_name": "<USER'S_LAST_NAME>",
          "company": "<USER'S_COMPANY>",
          "email": "<USER'S_EMAIL>@<DOMAIN>"
        }"

The account that will be created will be owned and managed by the user provided in the Create Account request. This user can then log into the Stitch web interface, receive emails from Stitch, etc.

When successful, this endpoint returns a status of 200 OK and an object with access_token and stitch_account_id properties:

{
  "access_token": "<ACCESS_TOKEN>",
  "stitch_account_id": <STITCH_CLIENT_ID>
}

Your application should store the access_token and stitch_account_id somewhere secure, as these credentials will be used to make calls to the API.

Step 2: Authenticate your API requests

Lastly, use the access_token in the header of your API requests to authenticate to the API:

curl GET https://api.stitchdata.com/v4/sources
     -H 'Authorization: Bearer <ACCESS_TOKEN>'

Generate tokens and authenticate using OAuth2

If you prefer to use OAuth, or to connect to a user’s existing Stitch client account, you can also use this approach:

• Step 1: Send the user to Stitch from your application

• Step 2: Get the user’s consent

• Step 3: Callback to your application

• Step 4: Exchange tokens

• Step 5: Authenticate your API requests

Step 1: Send the user to Stitch from your application

To initiate the authorization flow, the user will click a link to Stitch that includes your application’s API client ID. This is the partner_id you obtained when you registered your application. For example:

https://app.stitchdata.com/oauth/authorization?client_id={PARTNER_ID}

While only your partner_id is required, the URL may also include the following parameters:

Step 2: Get the user's consent

If the user isn’t already signed into their Stitch client account, they will be prompted to do so or create a new account, if need be.

Once signed in, the user will be shown a screen explaining that your application has requested access to their Stitch account. They will be prompted to accept or reject this request.

Step 3: Callback to your application

When the user accepts or denies the request, they will be redirected to the callback URL (redirect_uri) you provided when you registered your application with Stitch.

If the user denies the request, Stitch will include error details:

https://yourapplication.com/callback?error=access_denied

If the user accepts the request, the callback will include a temporary authorization code to be used in the next step:

https://yourapplication.com/callback?code=<STITCH_AUTHORIZATION_CODE>

Note: Each temporary authorization code can only be used once and expires five minutes after creation.

Step 4: Exchange tokens

Lastly, when your application receives the user’s request to the callback URL, it should make a request to the Stitch OAuth endpoint to exchange the temporary authorization code for a permanent access token:

curl https://api.stitchdata.com/oauth/token 
     -d client_secret=<CLIENT_SECRET>
     -d code=<STITCH_AUTHORIZATION_CODE>
     -d grant_type=authorization_code

If successful, Stitch will respond with the following:

{
  "token_type": "bearer",
  "access_token": "<ACCESS_TOKEN>",
  "stitch_account_id": <STITCH_ACCOUNT_ID>
}

Your application should store the access_token and stitch_account_id somewhere secure, as these credentials will be used to make calls to the API.

Step 5: Authenticate your API requests

Lastly, use the access_token in the header of your API requests to authenticate to the API:

curl GET https://api.stitchdata.com/v4/sources
     -H 'Authorization: Bearer <ACCESS_TOKEN>'

Next steps

To learn more about the Stitch API, refer to the API reference.