Authentication

Covers how we do authentication (and authorization) in the Spendesk API.

Access Tokens

Your first step in interacting with our APIs will be to authenticate in order to get an access token. There are two ways to do retrieve an access token:

  • API Key - using the auth endpoints
  • OAuth2 - using the oauth2 endpoints

πŸ“˜

Access tokens are valid for up to 1 hour, at which point any requests using them will return a 401 error and a new token will need to be requested.

:warning: As with all things related to security, tokens should be stored securely.

Which method you use will depend on you use case.

For Spendesk customers wanting to build their own direct integration, the API Key flow is the simpler option.

For Spendesk partners wanting to build integrations that customers will use, the OAuth2 flow is recommended.

API Keys

Using the API Key flow is the simpler of the two options and requires a single request for the access token to /auth/token.

You can manage your API keys directly by logging into Spendesk and navigating to Settings -> Integrations.

πŸ“˜

API keys can be valid for up to a maximum of 1 year.

This request uses your API Key configuration, you must provide your id and secret in the format id:secret then base64 encode it. You'll end up with something like:

  • plain: my_id:my_secret
  • encoded: bXlfaWQ6bXlfc2VjcmV0

Then you're ready to make a call to authenticate at auth/token using that encoded value in the Authorization header.

To get a new token, for example when one has expired, simply make another call to the auth/token endpoint using the id and secret.

Our quickstart guide covers this flow end-to-end, so we recommend following that to get a feel for this.

OAuth2

We use a common OAuth2 flow for when client credentials are required to authenticate on behalf of a customer. This follows these general steps:

  • Your system first makes a call to our /oauth2/authorize endpoint using your client id
  • We send back a 'redirect URL' to the Spendesk frontend which your system should redirect to
  • On Spendesk, the customer can login and approve the oauth connection between our systems
  • Once successful, Spendesk redirects back to your frontend with a 'connection code' in the URL
  • Your system makes a final call to our oauth2/token/create endpoint using the connection code
  • If this is successful, we send back both an access token as well as a refresh token
  • Use the access token in any subsequent API calls for this customer, for example to /payables
  • Use the refresh token request request new access tokens using the oauth2/token/refresh endpoint

πŸ“˜

Access tokens via OAuth2 are scoped to the specific organisation that approved the connection.

When the access token is expired, instead of starting the flow again, the oauth2/token/refresh endpoint can be used to 'refresh' the connection and generate a new token. You can either:

  • Wait until you see a 401 to request a new token via the /refresh
  • Proactively request new tokens before the 1 hour expiry time