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

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiIxIiwidG9rZW5fdHlwZSI6IkFDQ0VTUyIsImFsZyI6IlJTNTEyIn0eyJpc3MiOiJiYWNrZW5kLWNvcmUiLCJqdGkiOiI1ODdkMTQ3My05ODU5LTRhMDAtYTUwNS1iZTgwMDUzYmJiMzUiLCJpYXQiOjE1NzU5NzE1ODEsInN1YiI6IjFiMDAxNWUzLWNjNGYtNGRhNi05NzYxLWZiYTc0eyJ0eXAiOiJKV1QiLCJraWQiOiIxIiwidG9rZW5fdHlwZSI6IkFDQ0VTUyIsImFsZyI6IlJTNTEyIn0eyJpc3MiOiJiYWNrZW5kLWNvcmUiLCJqdGkiOiI1ODdkMTQ3My05ODU5LTRhMDAtYTUwNS1iZTgwMDUzYmJiMzUiLCJpYXQiOjE1NzU5NzE1ODEsInN1YiI6IjFiMDAxNWUzLWNjNGYtNGRhNi05NzYxLWZiYTc0",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "JqdGkiOiI1ODdkMTQ3MyeyJ0eXAiOiJKV1QiLCJraWQiOiIxIiwidG9rZW5fdHlwZSI6IkFDQ05ODU5LTRhMDAtYTUwNS1iZTgwMDUzYmJiMzUiLCJpYXQiOjE1NzU5NzE1ODEsInN1YiI6IjFiMDAxNWUzLWNjNGYtNGRhNi05NzYxLWZiYTc0eyJ0eXAiOiJKV1QiLCJraWQiOiIxIiwidG9rZW5fdHlwZSI6IkFDQ0VTUyIsImFsZyI6IlJTNTEyIn0eyJpc3MiOiJiYWNrZW5kLWNvcmUiLCJqdGkiOiI1ODdkMTQ3My05ODU5LTRhMDAtYTUwNS1iZTgwMDUzYmJiMzUiLCJpYXQiOjE1NzU5NzE1ODEsInN1YiI6IjFiMDAxNWUzLWNjNGYtNGRhNi05NzYxLWZiYTc00VTUyIsImFsZyI6IlJTNTEyIn0eyJpc3MiOiJiYWNrZW5kLWNvcmUiLC",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "3bf00b63-7188-4b04-aa27-d78e4cd32c01",
    "scope": "ACCOUNT_ADMIN USER"
}

import requests, json, os

# Define the directory path
up42_directory = os.path.expanduser("~/.up42")

# Create the directory if it doesn't exist
if not os.path.exists(up42_directory):
    os.makedirs(up42_directory)

# Specify the file path
credentials_file_path = os.path.join(up42_directory, "credentials.json")

# Check if the file already exists before creating it
if not os.path.exists(credentials_file_path):
    # Create an empty credentials.json file
    with open(credentials_file_path, "w") as credentials_file:
        print(f"The file {credentials_file_path} has been created.")
        pass
else:
    print(f"The file {credentials_file_path} already exists.")

# Load credentials from a file
with open(credentials_file_path, "r") as f:
    credentials = json.load(f)

# Check that authentication works
def auth(username, password):

    response = requests.post(
        f"https://auth.up42.com/realms/public/protocol/openid-connect/token",
        data=dict(username=username,
                  password=password,
                  grant_type="password",
                  client_id="up42-api")
    )

    result = response.json()
    return result["access_token"]

class BearerAuth(requests.auth.AuthBase):
    def __init__(self, token):
        self.token = token
    def __call__(self, r):
        r.headers["authorization"] = "Bearer " + self.token
        return r

token = auth(credentials["username"], credentials["password"])

def function_name(variable_name):

    # Authenticate
    token = auth(credentials["username"], credentials["password"])

    # Run the function
    response = requests.get(
        f"https://api.up42.com/v2/endpoint-path/{variable_name}",
        auth=BearerAuth(token),
    )

    return response

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 eyJ0eXAiOiJKV1QiLCJraWQiOiIxIiwidG9rZW5fdHlwZSI6IkFDQ0VTUyIsImFsZyI6IlJTNTEyIn0eyJpc3MiOiJiYWNrZW5kLWNvcmUiLCJqdGkiOiI1ODdkMTQ3My05ODU5LTRhMDAtYTUwNS1iZTgwMDUzYmJiMzUiLCJpYXQiOjE1NzU5NzE1ODEsInN1YiI6IjFiMDAxNWUzLWNjNGYtNGRhNi05NzYxLWZiYTc0eyJ0eXAiOiJKV1QiLCJraWQiOiIxIiwidG9rZW5fdHlwZSI6IkFDQ0VTUyIsImFsZyI6IlJTNTEyIn0eyJpc3MiOiJiYWNrZW5kLWNvcmUiLCJqdGkiOiI1ODdkMTQ3My05ODU5LTRhMDAtYTUwNS1iZTgwMDUzYmJiMzUiLCJpYXQiOjE1NzU5NzE1ODEsInN1YiI6IjFiMDAxNWUzLWNjNGYtNGRhNi05NzYxLWZiYTc0

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.up42.com instead of api.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.