Server-side quickstart

This quickstart is for partners calling the Embedded Banking REST API directly from a backend service and owning the UI themselves. Dropping Tesouro-hosted React components or widgets into a frontend instead? Follow the Quick start under Embedded components.

Get your credentials

Tesouro issues a client ID and client secret during onboarding. To request access, have your designated team lead submit an access request.Store the client secret in a secrets manager. It is not recoverable after creation — if lost, you must submit a new access request.

Generate an access token

Exchange your credentials for a short-lived Bearer token using the OAuth 2.0 client_credentials grant against the sandbox token endpoint.

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'

Response

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

The token is valid for expires_in seconds (typically one hour). Cache it on your server and request a new one before it expires — don’t fetch a new token on every API call.

Make your first authenticated call

Pass the token in the Authorization header. A safe first call is GET /embedded-banking/v1/bank-accounts, which returns the bank accounts visible to your application.

Request

curl --request GET 'https://api.sandbox.tesouro.com/embedded-banking/v1/bank-accounts?limit=10' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Accept: application/json'

Response

{
  "data": [
    {
      "id": "eaae8b39-e86b-4cce-9fa3-68f633c08ab6",
      "nickname": "Operating",
      "accountNumber": "100000000123",
      "routingNumber": "021000021",
      "balance": { "value": 150000, "currencyCode": "USD" },
      "status": "ACTIVE",
      "bankAccountReference": null,
      "createdDateTime": "2026-01-15T12:34:56Z"
    }
  ],
  "nextPaginationToken": null,
  "prevPaginationToken": null
}

A 401 means the token is missing, expired, or malformed. A 403 means the token is valid but lacks the scope the endpoint requires — every endpoint in the API reference lists its required scope.

Switch to production by replacing the host with https://api.tesouro.com and using your production credentials. See Environments for the full breakdown.

Next steps

Authentication overview — token lifecycle, revocation, and acting on behalf of a user via token exchange
Application flow — start a bank account application with POST /embedded-banking/v1/bank-account-applications (filter the API reference to the Bank Account Applications tag)
Money movement — initiate book, ACH, RTP, and FedNow transfers
Webhooks — receive asynchronous events for application decisions and transfer state changes
Pagination, sorting, and filtering — conventions every list endpoint follows

Getting started

Authentication

Organizations

Users

Bank account applications

Bank accounts

Webhooks

Money movement

Transactions

Embedded components

White-label

Server-side quickstart

Next steps

​Next steps

Next steps