API Reference

Authentication

We use the OAuth 2.0 protocol for authentication and authorization, supporting the common OAuth 2.0 scenario of web server applications. This guide outlines the OAuth 2.0 client credentials flow for secure authentication, managing access tokens, and ensuring client credentials are securely maintained.

📘

You should obtain the client credentials from our Customer Support team. You will be given a Client ID, a Client Secret, and your respective Account ID.

To start, you will need to request an access token from our Authorization Server. See the example below.

Request Access Token

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={CLIENT_ID}" \
  -d "client_secret={CLIENT_SECRET}" \
  -d "grant_type=client_credentials" \
  https://api.astrada.co/auth/realms/{ACCOUNT_ID}/protocol/openid-connect/token

Note: replace the CLIENT_ID, CLIENT_SECRET, and ACCOUNT_ID with the values you received during the onboarding.

Example response

As a response, you should get the access token that you must then use to access our API.

{
  "access_token": "RsT5OjbzRn430zqMLgV3Ia",
  "token_type": "Bearer",
  "expires_in": 300
}

Access tokens are temporary credentials. Once expired, a new token needs to be requested.

Using the Access Token

Once you successfully get the access token, you can request our API.

curl -X GET \
  -H "Authorization: Bearer RsT5OjbzRn430zqMLgV3Ia" \
  -H "Content-Type: application/json" \
  https://api.astrada.co/subaccounts

Common Errors

Having issues authenticating with our API? Getting a 401 Unauthorized as a response? There are some common errors and potential causes for this to happen.

  • Incorrect Account identifier specified in URI /auth/realms/{ACCOUNT_ID}/protocol/openid-connect/token. This is required to identify to which Account the client is authenticating.
  • Incorrect Client ID/Client Secret. Credentials must be valid.

See Authorization errors for more details on potential errors and causes.