API concepts

Work with Tesouro’s Implementation team to get set up with access to our environment and configure your branding.

Authentication

The first steps for integrating with Tesouro are to:

Activate your developer account
Receive your API access key credentials
Create and authenticate your first JSON Web Token (JWT) to Tesouro.

Access your organization’s API access key credentials

Your organization’s API access key and secret are created by Tesouro and shared with you. To receive access:

Have your designated team lead submit your access request here (external site managed by Tesouro)
Tesouro will email you an API access key and secret that will require passwordless authentication via email address.

Create and authenticate your JWT

Create a JWT, then add it to the header of your call to query the Tesouro Sandbox environment

Authentication Request

  curl --location 'https://api.sandbox.tesouro.com/openid/connect/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_id=CLIENT_ID' \
    --data-urlencode 'client_secret=CLIENT_SECRET'

Authentication Request

{
  "access_token": "efJhbGcifiJv4zI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Example Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ADD_TOKEN_HERE" \
  -d '{
      "query": "query bankAccounts($input: BankAccountQueryInput!) {
          bankAccounts(input: $input) {
            items {
              bankAccountBalance
              id
              bankAccountNickname
              bankAccountNumber
              routingNumber
            }
          }
        }",
      "variables": {
        "input": {
          "where": {"id": {"eq": "eaae8b39-e86b-4cce-9fa3-68f633c08ab6"}},
          "paging": {
            "skip": 0,
            "take": 10
          }
        }
      }
    }' \
  https://api.sandbox.tesouro.com/graphql

Example Response

{
  "data": {
    "organization": {
      "id": "66f41f51-cc83-440b-948f-afe3d4c57406",
      "businessName": "Tesouro Docs Sandbox"
    }
  }
}

For production, use https://api.tesouro.com/graphql instead of https://api.sandbox.tesouro.com/graphql with production credentials

Token Exchange for User Impersonation

For seamless widget and API experiences, Tesouro supports OAuth 2.0 Token Exchange (RFC 8693). This allows your application to impersonate users on the Tesouro platform by exchanging a user JWT for an access token.

Token Exchange Request

curl --location 'https://api.sandbox.tesouro.com/openid/connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'client_secret=CLIENT_SECRET' \
  --data-urlencode 'subject_token=USER_JWT_TOKEN' \
  --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token'

Token Exchange Response

{
  "access_token": "efJhbGcifiJv4zI1NiIsInR5cCI6IkpXVCJ9...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Subject Token Requirements: Your JWT must include both the user’s unique identifier in the sub claim and the user’s email address in the email claim. The returned access token contains RFC 8693 delegation claims indicating it’s an impersonated token.

Security: Users can only be impersonated within their assigned application context. Cross-application impersonation is prevented for security.

Embedded components authenticate each user with a widget token: an encrypted JWE that your backend mints, wrapping a token exchange request for that user. Tesouro provides the client ID, client secret and 32-byte widget secret it needs during onboarding. User token documents the token’s claims, encryption and lifetime.

Additional resources

Learn more about JWTs and OAuth 2.0 Token Exchange (RFC 8693)

Getting started

Authentication

Organizations

Users

Bank account applications

Bank accounts

Webhooks

Money movement

Transactions

White-label

Authentication

Access your organization’s API access key credentials

Create and authenticate your JWT

Token Exchange for User Impersonation

Widget Authentication

Additional resources

​Authentication

​Access your organization’s API access key credentials

​Create and authenticate your JWT

​Token Exchange for User Impersonation

​Widget Authentication

​Additional resources

Authentication

Access your organization’s API access key credentials

Create and authenticate your JWT

Token Exchange for User Impersonation

Widget Authentication

Additional resources