Authentication
The TreasurySpring Public API uses OAuth 2.0. We support two grant types, each suited to a different integration shape.
Pick a grant type
| Grant type | Use case |
|---|---|
| Client Credentials | A TreasurySpring user accessing their own data. The credentials are issued by the entity owner and represent that user. Each call is logged as that user. |
| Code Authorisation (Auth Code + PKCE) | A partner system integrating shared users with TreasurySpring — typically when end-users of the partner platform should each act with their own TreasurySpring identity. |
Client Credentials — when
- A treasurer at one organisation wires their own TMS into TreasurySpring.
- A back-office team builds an internal dashboard.
- A scheduled reporting job runs against the API.
The credential is generated in the portal: Account Information → Developer Settings → Generate client_id / client_secret. One credential pair can be granted access to multiple entities the user is permissioned on — in that case, each request specifies entityCode to scope the action.
Code Authorisation — when
- A multi-tenant treasury platform offers TreasurySpring as one of several investment venues, and wants each end-user's TreasurySpring actions to be attributed to that user.
- A partner application needs per-user audit trails in TreasurySpring rather than rolling everything up under a single service identity.
Please contact your TreasurySpring account manager for the technical specifics of provisioning a code-authorisation client — client application setup, redirect URI registration, and per-user consent.
Trusted-system vs impersonation patterns
When a partner platform integrates on behalf of multiple end-users, there are two architectural patterns to choose between. They differ in whose name appears in the TreasurySpring audit trail.
Trusted-system pattern — the partner authenticates with a single Client Credentials token and calls the API on behalf of all its users. Every TreasurySpring audit log entry is attributed to the partner system, not the individual end-user. The partner system is responsible for maintaining its own internal mapping between end-users and the actions they triggered.
- Simpler to operate (one credential).
- TreasurySpring side sees one actor; the partner is the system of record for who did what.
Impersonation pattern — the partner uses Code Authorisation to obtain a token per end-user. Each TreasurySpring action is attributed in TreasurySpring's audit log to the individual user.
- TreasurySpring is the system of record for who did what.
- More setup; each user goes through an OAuth consent flow.
For regulated environments where end-user attribution is a compliance requirement, the impersonation pattern is usually the right fit.
Base URLs
| Environment | API base | OAuth token endpoint |
|---|---|---|
| Production | https://api.treasuryspring.com/api/v1 | https://api.treasuryspring.com/oauth/token |
| Sandbox | https://api.sandbox.treasuryspring.com/api/v1 | https://api.sandbox.treasuryspring.com/oauth/token |
Please note that the OAuth token endpoints sit at the root of each environment, not under /api/v1 — they are routed differently from the API endpoints. Constructing the token URL by concatenating the API base with /oauth/token will return a 404, so it's worth taking the URLs above as-is.
Token lifetime and refresh
Access tokens are returned by the /oauth/token endpoint with an expires_in value (in seconds). The typical lifetime is several hours, but we recommend reading expires_in and refreshing before it expires rather than hard-coding the lifetime in your client.
For Client Credentials, refresh means "request a new token using the same credentials". There is no separate refresh token; the same client_id / client_secret can be re-exchanged on demand. Tokens are reusable until they expire, so caching and reusing the token across calls is more efficient than requesting a new one per API call.
For Code Authorisation, a refresh token is issued alongside the access token and should be used to extend a session without re-prompting the end-user.
Sandbox API keys (testing convenience)
Alongside OAuth, the sandbox environment supports an API key mode for ease of testing — you can generate one from the portal's Developer Settings under the sandbox environment. The API key is sent as Authorization: Bearer <key> and bypasses the token exchange. For production data, OAuth is required.
SSO federation
TreasurySpring's portal supports SSO federation for partner organisations that want to centralise identity for portal users. SSO affects portal login (the path through which Client Credentials are minted), not the API authentication itself. If your organisation would like portal SSO set up, please reach out to your account manager.
Worked example
- Quickstart — end-to-end token exchange and authenticated call.
- Sandbox guide — getting credentials.
- Errors & responses — what auth failures look like and how to recover.