API reference

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

POST/oAuth/token

Returns 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.

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_typestringRequired

    The grant type: password to start a new session, or refresh_token to renew one.

    Allowed values: password, refresh_token.

  • client_idstringRequired

    Your Xtrm-supplied client ID.

  • client_secretstringRequired

    Your Xtrm-supplied client secret.

  • refresh_tokenstringOptional

    The refresh_token returned by a previous successful token request. Required only when renewing a token (grant_type is refresh_token).

Response fields

  • access_tokenstring

    The bearer token to send with your other Xtrm API calls.

  • token_typestring

    The token type: bearer.

  • expires_ininteger

    Seconds until the access_token expires. A new token lasts 24 hours; while your current token is still valid, Xtrm returns that same token, and expires_in is the time it has left.

  • refresh_tokenstring

    Token to pass with grant_type set to refresh_token to renew the session. It expires 60 days after it's issued. Every token response returns your current refresh_token, so keep the one from your most recent response.

  • .issuedstring

    When the token was issued, as a date string, e.g. "Tue, 27 Oct 2026 14:58:21 GMT".

  • .expiresstring

    When the token expires, as a date string, e.g. "Wed, 28 Oct 2026 14:58:21 GMT".

  • client_idstring

    The client ID the token was issued to.

Related: List company wallets · Check whether an individual recipient exists