Authentication
Sail handles sensitive data, including personally identifiable information (PII) and ACH deposit credentials, so authentication uses multiple layers of protection. Every API request requires an API key, while endpoints that return PII also require an ephemeral user token.
API keys
Authenticate every API request by including your API key in the Authorization header:
Each API key is assigned a fixed set of scopes that determine which endpoints it can access. A key can only make requests to endpoints covered by its assigned scopes. If a request targets an endpoint outside those scopes, the API returns 403 insufficient_key_scope.
| Scope | Description |
|---|---|
expenses | Reading expenses, creating the connections that produce them |
benefit_account | Creating HSA/FSA connections, reading account and balance data |
account_numbers | Reading masked and revealing full deposit numbers |
identity | Reading originated and administrator-reported identity (PII) |
ingest | Pushing your own transaction data to an external connection |
token_admin | Minting and revoking ephemeral user tokens |
Ephemeral user tokens
Endpoints that return PII or account numbers need a second credential: an ephemeral user token, passed in the x-sail-user-token header alongside your API key. This two-credential model ensures that no single key can access sensitive data on its own. Create one through Mint Ephemeral User Token. Tokens expire after a set time (15 minutes by default, 1 hour at most) and are meant for one-time use.
The following endpoints need an ephemeral user token:
- Get Originated Identity
- Get Account Owner Identity
- Get Account & Routing Numbers
- Reveal Full Account Number
To revoke all active tokens for a user, call Revoke All User Tokens.
The token_admin key is exclusive
A key with the token_admin scope can only mint and revoke tokens. It can’t hold any other scope, and it can’t access data. This separation is enforced at key creation.
To reach a PII endpoint, you need two keys working together:
- A key with the
token_adminscope to mint the ephemeral user token. - A key with a data scope (for example,
identityoraccount_numbers) to make the request with that token.
Connection-level access
When a user links a data source (a card, merchant account, or HSA/FSA administrator), that link is called a connection. Each connection has its own set of enabled capabilities. A request can fail even if your key has the right scope, if the connection itself doesn’t have that capability turned on. When this happens, the API returns 403 product_not_enabled. See Account Connections for more detail.