Authenticate to the Atlas API

Atlas Core · Guides · 15 min

Atlas supports three OAuth 2.0 methods for authenticating API requests:

Method	When to use it
Client Credentials	Server-to-server integrations that do not require an individual user to sign in.
Authorization Code	Server-based web applications that access Atlas on behalf of a user.
Authorization Code with PKCE	Applications that should not store a client secret, such as single-page applications (SPAs).

This guide walks through all three methods using cURL. Choose the workflow that matches your integration. Each workflow ends by using an access token to make a GET request to retrieve Atlas account settings.

Before you begin

You need:

• Access to the Atlas portal and the account you want to access through the API.
• Permission to create an API client at the account level.
• cURL to send the API requests.
• A unique Client ID for the API client you create.
• For Authorization Code or PKCE, a callback URL for your application.

The Atlas API base URL used in this guide is:

https://api.titan.host/api/v2

The examples use placeholders for values specific to your API client and application.

Placeholder	Replace with
<CLIENT_ID>	The Client ID you assign when creating the API client.
<CLIENT_SECRET>	The secret generated for the API client.
<CALLBACK_URL>	The callback URL configured for your application.
<AUTHORIZATION_CODE>	The authorization code returned after a user authorizes the application.
<ACCESS_TOKEN>	The access token returned by Atlas.
<STATE>	An optional state value used by your application during the Authorization Code flow.
<CODE_CHALLENGE>	The PKCE challenge generated by your application or OAuth library.

Replace the angle brackets and the text inside them. Do not send the placeholders as literal values.

A few API basics

An API request is a message your application sends to Atlas. The URL identifies the resource you want to access. The method describes the action; this guide uses GET to retrieve data and POST when requesting tokens. A header carries information with a request, such as an access token. The response is the status and any data Atlas sends back.

How authentication works

Atlas uses OAuth 2.0. Your application first obtains an access token using one of the three supported authentication methods. Authenticated API requests then send that token using the Bearer authentication scheme:

Authorization: Bearer <ACCESS_TOKEN>

The setup process differs depending on whether your application uses API Server Access or API User Access.

• Client Credentials clients are created under API Server Access.
• Authorization Code and Authorization Code with PKCE clients are created under API User Access.

Treat client secrets, access tokens, refresh tokens, authorization codes, and other authentication values as sensitive credentials. Store them securely and do not include them in public code, documentation, or screenshots.

Client Credentials and standard Authorization Code integrations use a Client Secret. PKCE is intended for applications that should not store a Client Secret.

Method 1: Client Credentials

Client Credentials is intended for server-to-server integrations that do not require an individual user to sign in.

1. Create an API Server Access client

1. Sign in to the Atlas portal and navigate to the account level.
2. From the right-hand menu, select API Server Access.
3. Click ADD CLIENT.
4. Enter a unique Client ID.
5. Select the VOIP checkbox.
6. Click SAVE.
7. In the list of API clients, click the View Secret icon for the client.

Securely record the Client ID and Client Secret. You will use both values to request an access token.

2. Request an access token

Send a POST request to the /credential/token endpoint.

Run:

curl -X POST \
  "https://api.titan.host/api/v2/credential/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&scope=voip"

A successful response contains information about the generated token. The Access value is the token you will use to authenticate API requests.

For example:

{
  "ClientID": "<CLIENT_ID>",
  "UserID": "<your user id>",
  "Scope": "voip",
  "Access": "<ACCESS_TOKEN>",
  "AccessExpiresIn": 7200
}

The complete response contains additional fields. For authentication, securely record the value returned in Access.

Client Credentials access tokens are valid for 7,200 seconds (2 hours). After the token expires, repeat this step to obtain a new token.

3. Make a successful GET request

Use the /accountsettings endpoint to retrieve the settings for the account.

Run:

curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  "https://api.titan.host/api/v2/accountsettings"

Replace <ACCESS_TOKEN> with the Access value returned by the token request.

A successful response containing the account settings confirms that your application has authenticated to the Atlas API.

If the request does not succeed, verify the Client ID and Client Secret, confirm that the token has not expired, and make sure the Bearer token was copied correctly. Once the /accountsettings GET request succeeds, you have completed the Client Credentials workflow.

Method 2: Authorization Code

Authorization Code is intended for server-based web applications that need a user to sign in and authorize access to Atlas.

1. Create an API User Access client

1. Sign in to the Atlas portal and navigate to the account level.
2. From the right-hand menu, select API User Access.
3. Click ADD CLIENT.
4. Enter a unique Client ID.
5. Enter the callback URL for your application.
6. Select the VOIP checkbox.
7. Click SAVE.
8. In the list of API clients, click the View Secret icon for the client.

Securely record the Client ID and Client Secret.

The callback URL is the location in your application where Atlas returns the user after authorization.

2. Send the user to Atlas for authorization

Send the user to the /code/authorize endpoint with your Client ID, callback URL, requested scope, and an optional state value.

The request follows this format:

https://api.titan.host/api/v2/code/authorize?client_id=<CLIENT_ID>&redirect_uri=<CALLBACK_URL>&response_type=code&state=<STATE>&scope=voip

The state parameter is optional in the Atlas request. If your application uses it, Atlas returns the value to your callback URL after authorization.

Your callback URL must be URL encoded when included as the redirect_uri query parameter.

Atlas prompts the user to enter their portal username and password. The user is then asked to authorize access to the VOIP account-level API services.

3. Receive the authorization code

If the user enters valid credentials and authorizes the requested access, Atlas redirects the user to the callback URL configured for the API client.

The callback includes a code query parameter. If you supplied a state value, it is also returned.

For example:

<CALLBACK_URL>?code=<AUTHORIZATION_CODE>&state=<STATE>

Securely record the authorization code. Your application exchanges this code for an access token.

4. Exchange the authorization code for an access token

Send a POST request to the /code/token endpoint.

Run:

curl -X POST \
  -H "cache-control: no-cache" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d "code=<AUTHORIZATION_CODE>&grant_type=authorization_code&redirect_uri=<CALLBACK_URL>" \
  "https://api.titan.host/api/v2/code/token"

Replace the placeholders with your Client ID, Client Secret, authorization code, and callback URL. The callback URL must match the URL used during authorization.

A successful response includes an access_token:

{
  "access_token": "<ACCESS_TOKEN>",
  "client_id": "<CLIENT_ID>",
  "expires_in": 7200,
  "redirect_url": "<CALLBACK_URL>",
  "refresh_token": "<your refresh token>",
  "scope": "VOIP",
  "token_type": "Bearer",
  "user_id": "<your user id>"
}

Securely record the value returned in access_token.

5. Make a successful GET request

Use the /accountsettings endpoint to retrieve the settings for the account.

Run:

curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  "https://api.titan.host/api/v2/accountsettings"

Replace <ACCESS_TOKEN> with the access_token returned by the token request.

A successful response containing the account settings confirms that the user authorized your application and that the access token can be used with the Atlas API.

If the request does not succeed, verify the callback URL, authorization code, Client ID and Client Secret, and access token. Once the /accountsettings GET request succeeds, you have completed the Authorization Code workflow.

Method 3: Authorization Code with PKCE

Authorization Code with Proof Key for Code Exchange (PKCE) is intended for applications that should not store a Client Secret, such as native applications or browser-based single-page applications.

Atlas recommends using an OAuth or PKCE library appropriate for your application's programming language to generate and manage the PKCE values.

1. Create an API User Access client

1. Sign in to the Atlas portal and navigate to the account level.
2. From the right-hand menu, select API User Access.
3. Click ADD CLIENT.
4. Enter a unique Client ID.
5. Enter the callback URL for your application.
6. Select the VOIP checkbox.
7. Click SAVE.

Your application uses the Client ID and callback URL during authorization.

2. Generate the PKCE challenge

Use the OAuth or PKCE library appropriate for your application to generate the challenge value required for the authorization request.

Securely retain any related PKCE values your library requires to complete the authorization flow.

3. Send the user to Atlas for authorization

The PKCE flow uses the /code/authorize endpoint with additional PKCE parameters.

The Atlas API specification documents the authorization request in this form:

https://api.titan.host/api/v2/code/authorize?client_id=<CLIENT_ID>&redirect_uri=<CALLBACK_URL>&response_type=code&code_challenge=<CODE_CHALLENGE>&code_challenge_method=plain

Replace <CLIENT_ID>, <CALLBACK_URL>, and <CODE_CHALLENGE> with the values for your application. The callback URL must be URL encoded when included as the redirect_uri query parameter.

Atlas then handles user authentication and authorization through the Authorization Code flow.

4. Complete the PKCE token exchange

After authorization, Atlas redirects the user to the configured callback URL with an authorization code.

Your application must exchange that authorization code using the PKCE values associated with the authorization request to obtain an access token.

The current Atlas API specification documents the PKCE authorization request but does not provide the complete PKCE token-exchange request or its verifier parameters. This guide does not assume undocumented request parameters.

Use the OAuth or PKCE library appropriate for your application and the implementation details provided for your Atlas environment to complete this step.

5. Make a successful GET request

After your application obtains an access token, use it to request the account settings:

curl \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  "https://api.titan.host/api/v2/accountsettings"

Replace <ACCESS_TOKEN> with the access token obtained through the PKCE flow.

A successful response containing the account settings confirms that the access token can be used with the Atlas API.

Once the /accountsettings GET request succeeds, you have authenticated to the Atlas API and are ready to make additional API requests using the same Bearer-token authentication method.