Skip to content
English
More support
Contact us
  • There are no suggestions because the search field is empty.

Authentication and token scopes

How to get a Remitian access token server-side, which headers every request needs, and how to pick the right token scope.

What it is

Every Remitian API request is authenticated with a short-lived access token plus your API Key. You request the token from your backend using your Client Application credentials and a scope that limits what the token can reach.

When you need it
  • Before any API call, and again whenever your token expires.
  • When your backend issues a token for a browser or mobile client and you need to limit what that user can access.
How it works
  1. Request a token from your server. Call POST /v1/auth/token with your externalIntegratorId, clientApplicationId, apiSecret and a scope. Always do this server-side, because the request contains your Client Secret. Never generate tokens in browser or mobile code.
  2. Send two headers on every request: Authorization: Bearer followed by your access token, and x-api-key with your API Key.
  3. Refresh when it expires. Tokens last 10 minutes by default. Request a new one when yours expires.
Scope Reaches Use it when
all All firms and taxpayers in the Client Application Your backend runs general operations across firms.
firm:{firmId} One firm and its taxpayers The user manages an entire firm.
firm:{firmId}:firmUser:{firmUserId} One firm user's resources The user is a firm accountant managing their own clients.
taxpayer:{taxpayerId} One taxpayer and their resources The user is a single taxpayer.

Always pick the most restrictive scope that does the job.

Common questions

Can I generate the token in the browser?

No. Generate it on your server and pass only the token to the client, scoped to what that user should access.

What do I do if our Client Secret is exposed?

Regenerate it immediately in the Developer Portal (Client Applications, then Regenerate). The old secret stops working at once. Update your systems, and contact support@remitian.com if you need help.

We lost the Client Secret. Can we retrieve it?

No. It is shown only once. Regenerate it in the Developer Portal.

Why does the token endpoint return 401 with valid credentials?

If your organization uses an IP allowlist, a token request from an unlisted IP gets the same 401 as invalid credentials. Check that you are calling from a listed IPv4 address.

Full documentation