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.


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

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:

POST /v3/accounts
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:

Response for POST /v3/accounts
{
  "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:

GET /v4/sources
curl -X "POST" "https://api.stitchdata.com/v4/sources" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json'

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

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:

Example authorization URL
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:

client_id
REQUIRED

Your API client ID. This is the partner_id that is obtained when your API access request is approved.

redirect_uri
OPTIONAL

The callback URL for your application, which will be used in Step 3.

Note: If provided as a URL parameter, then the value must match one of the redirect URIs provided with your application’s registration.

If not provided as a URL parameter, Stitch will fallback to the first redirect_uri associated with your API client.

email
OPTIONAL

The email address of the Stitch client owner. If provided, this value will be used to pre-populate the signup form.

first_name
OPTIONAL

The user’s first name. If provided, this value will be used to pre-populate the signup form.

last_name
OPTIONAL

The user’s last name. If provided, this value will be used to pre-populate the signup form.

company
OPTIONAL

The name of the company or organization to associate with the Stitch client account. If provided, this value will be used to pre-populate the signup form.

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:

GET /v4/sources
curl -X "POST" "https://api.stitchdata.com/v4/sources" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json'

Next steps

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