Authentication
The Xtrm API authenticates requests with bearer tokens. Exchange the API credentials that Xtrm gives you (client_id and client_secret) for an access_token, then send that token as a bearer token (Authorization: Bearer YOUR_ACCESS_TOKEN) with every other API call.
To get sandbox credentials, log in to your sandbox company account and go to Settings > Integrations > Get Credentials. On the same screen, request the IP addresses you will call the API from. Xtrm approves them. In production, you get your credentials and request your IP addresses the same way, in your live company account.
The token endpoint sits at the host root (https://xapisandbox.xtrm.com/oAuth/token in the sandbox, https://xapi.xtrm.com/oAuth/token in production), not under the /API/v4 base path that the other endpoints use.
#Get or renew an access token
/oAuth/tokenReturns an access_token, which you send as a bearer token on your other Xtrm API calls, and a refresh_token for renewing the session.
This call doesn't take a bearer token: it is how you get one. Your API credentials (client_id and client_secret), sent over HTTPS, authenticate it.
Set grant_type to password to start a new session, or to refresh_token to renew one. To renew, also send the refresh_token from a previous successful token response. Send refresh_token only when grant_type is refresh_token.
Note
Send the parameters form-encoded, with the headers Content-Type: application/x-www-form-urlencoded and Accept: application/json.
Important
The access_token stops working at the fixed expiry time set when it's issued (.expires), 24 hours after issue. Using the token doesn't extend it. To get a new one, renew with grant_type=refresh_token and your refresh_token, which expires 60 days after it's issued, or get a new token with grant_type=password. Once your refresh_token has expired, or if a refresh_token grant returns 400 with invalid_grant, use grant_type=password: that response carries a refresh_token for the next 60 days.
Note
A failed token request returns HTTP 400 with a body of the form {"error": "…", "error_description": "…"}. error is invalid_credentials when the client_id or client_secret is wrong, invalid_clientId when API access for these credentials has been deactivated or the refresh_token was issued to a different client_id, invalid_grant when the refresh_token isn't recognized, and unsupported_grant_type for any grant_type other than password or refresh_token.
Form parameters
grant_typestringRequiredThe grant type:
passwordto start a new session, orrefresh_tokento renew one.Allowed values:
password,refresh_token.client_idstringRequiredYour Xtrm-supplied client ID.
client_secretstringRequiredYour Xtrm-supplied client secret.
refresh_tokenstringOptionalThe
refresh_tokenreturned by a previous successful token request. Required only when renewing a token (grant_typeisrefresh_token).
Response fields
access_tokenstringThe bearer token to send with your other Xtrm API calls.
token_typestringThe token type:
bearer.expires_inintegerSeconds until the
access_tokenexpires. A new token lasts 24 hours; while your current token is still valid, Xtrm returns that same token, andexpires_inis the time it has left.refresh_tokenstringToken to pass with
grant_typeset torefresh_tokento renew the session. It expires 60 days after it's issued. Every token response returns your currentrefresh_token, so keep the one from your most recent response..issuedstringWhen the token was issued, as a date string, e.g.
"Tue, 27 Oct 2026 14:58:21 GMT"..expiresstringWhen the token expires, as a date string, e.g.
"Wed, 28 Oct 2026 14:58:21 GMT".client_idstringThe client ID the token was issued to.
Related: List company wallets · Check whether an individual recipient exists