API authentication

The UP42 API uses token-based bearer authentication. Generate an access token to call API endpoints.

To generate an access token that will be valid for 5 minutes, use this endpoint:

POST /realms/public/protocol/openid-connect/token HTTP/1.1
Host: auth.sa.up42.com
Content-Type: application/x-www-form-urlencoded

username=<your-email>&password=<your-password>&grant_type=password&client_id=up42-api

curl --location --request POST 'https://auth.sa.up42.com/realms/public/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=<your-email>' \
--data-urlencode 'password=<your-password>' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=up42-api'

Create a request body as follows:

1. Include a Content-Type header and set its value to application/x-www-form-urlencoded.

2. Retrieve the email address and password used for logging into the console. Use them as values in the following arguments:

   • Set the value of username to your email address.
   • Set the value of password to your password.

3. Add the grant_type=password string to the request. Don’t change the password value.

4. Add the client_id=up42-api string to the request. Don’t change the up42-api value.

Extract the access token from the response:

1
{
2
    "access_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiIxIiwidG9rZW5fdHlw<...>",
3
    "expires_in": 300,
4
    "refresh_expires_in": 1800,
5
    "refresh_token": "JqdGkiOiI1ODdkMTQ3MyeyJ0eXAiOiJKV1QiLCJraWQ<...>",
6
    "token_type": "Bearer",
7
    "not-before-policy": 0,
8
    "session_state": "3bf00b63-7188-4b04-aa27-d78e4cd32c01",
9
    "scope": "ACCOUNT_ADMIN USER"
10
}

The majority of UP42 endpoints require an access token in the Authorization header. Those endpoints, that allow requests without authentication, provide access to publicly available information — for example, to a list of all collections.

Add the word Bearer before the access token. An example usage:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiOiIxIiwidG9rZW5fdHlwZSI6IkFDQ0VTUyIsI

Access tokens are only valid for 5 minutes. Make sure you’re not using an expired access token. Otherwise, you’ll receive the HTTP 401 Unauthorized error.

This error might be caused by one of the following reasons:

• The credentials are wrong.
• grant_type=password or client_id=up42-api parameters are missing.
• The token has expired, and you need to re-request a new one.

Check the server URL. It should be auth.sa.up42.com instead of api.sa.up42.com, which is used for the rest of the endpoints.

The authentication request contains unspecified media types. Resolve this issue as follows:

• In the request header, add Content-Type: application/x-www-form-urlencoded.
• In the request body, add grant_type=password. Don’t change the password value.
• In the request body, add client_id=up42-api. Don’t change the up42-api value.