Language
OneAtlas API Guides
  1. Authenticate
    1. Get an Access Token from Your API Key
    2. Manage the API Keys Associated to a User
    3. Create Additional API Keys for a User
    4. List the API Keys Associated to a User
    5. Test an API Key
    6. Delete an API Key

Authenticate

Authentication is the process of proving your identity to the system. Identity is an important factor in OneAtlas access control decisions. Access to OneAtlas services are allowed or denied based on the identity of the requester.


If you do not have a OneAtlas account, please register here. You will receive login credentials for your account.

Note: If your account registration includes access to OneAtlas Basemap services, you will also receive a Basemap API Key. This key provides authorization to use the OneAtlas Basemap services.

For authorization to use the OneAtlas services, an access token is required. Every OneAtlas account has an API key; this API Key is used to generate an access token. To get your API key, please visit the API Key Generator page.

Note: Please ensure you protect your API key. If anyone else gains access to it, they will be able to make requests and use your balance.

Get an Access Token From Your API Key

An API Key is your digital signature identifying you as a user of OneAtlas services. Using this key, you will need to get an access token that enables authorization. Authorization refers to the process of determining what permissions an authenticated client has for a set of resources.


For security reasons this access token expires regularly, then it’s necessary to renew the authentication process to get a new one.


The endpoint to use to generate access tokens is described in the following table:

API Endpointhttps://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token
REST verbPOST
AuthenticationAPI Key
API ReferenceAuthentication API

The required parameters are listed in the table below:

ParametersRequiredDescription
apikeyyesThe OneAtlas API key associated with the service account to authenticate.
client_idyesThe API service group accessed. This service group can be retrieved by consulting the service documentation or calling the unprotected /well_known/serviceGroup URI on the service itself.
grant_typeyesOneAtlas Grant type.Must be the value api_key for API key authentication.

Note: The value of the parameter “client_id” depends on the services you want to access. If you want to use the OneAtlas services, then use the “IDP” value to generate an access token. However, if you want to use the API key management services (at https://authenticate.foundation.api.oneatlas.airbus.com), then use the “AAA” value to generate an access token.

Below is an example to retrieve an access token with the API Key to use with OneAtlas services:

curl -X POST https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'apikey=<api_key>&grant_type=api_key&client_id=IDP'
var data = "apikey=&grant_type=api_key&client_id=IDP";

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token");
xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);
headers = {
    'Content-Type': 'application/x-www-form-urlencoded',
}

data = [
  ('apikey', '<api_key>'),
  ('grant_type', 'api_key'),
  ('client_id', 'IDP'),
]

response = requests.post('https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token', headers=headers, data=data)

print(response.text)

If the authentication information is valid, then the return JSON structured provides an access token and its validity duration.

{
    "access_token": "<access_token>",
    "expires_in": 3600,
    "token_type": "bearer"
}

However, if authentication information is invalid or omitted, an error message will be returned with status code 403:

{
  "error": "access_denied",
  "error_description": "Access denied"
}

Important: For security reason, providing an incorrect API key will automatically suspend the authorization to access the API for a limited period of time. During this suspension period, the user will receive a 403 error, even if the API key is valid.

For more ease, let’s define it as an environment variable for your own user or globally if necessary.

export MY_TOKEN=<api_key>

Manage the API Keys Associated to a User

A user can generate up to 10 API keys. This could be convenient if you need to access to the One Atlas services in different context, for example from different tools or validity periods.

Important: The access to these endpoints requires authentication with an access token. Please note that this token must be generated using an existing API key and the procedure described in the previous paragraph Key, but with the “client_id” parameter set to the value “AAA”.

Create Additional API Keys for a User

The endpoint to create a new API key associated to a user is described in the following table:

API Endpointhttps://authenticate.foundation.api.oneatlas.airbus.com/api/v1/apikeys
REST verbPOST
AuthenticationJWT Token
API ReferenceAPIKeys API

Below is an example to retrieve an access token using the API key with a cURL request:

curl -X POST \
  https://authenticate.foundation.api.oneatlas.airbus.com/api/v1/apikeys \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer <access_token>" \
  -H "Cache-Control: no-cache" \
  -d '{ "description": "New API key for GIS tools" }'
var data = "%7B%20%22description%22%3A%20%22New%20API%20key%20for%20GIS%20tools%22%20%7D=";

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://authenticate.foundation.api.oneatlas.airbus.com/api/v1/apikeys");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer  <access_token>");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);
import requests

url = "https://authenticate.foundation.api.oneatlas.airbus.com/api/v1/apikeys"

payload = "%7B%20%22description%22%3A%20%22New%20API%20key%20for%20GIS%20tools%22%20%7D="
headers = {
    'Content-Type': "application/json",
    'Authorization': "Bearer <access_token>",
    'Cache-Control': "no-cache",
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

In this case, the user has only one API key :

{
  "id": "<uid>",
  "description": "New API key for GIS tools",
  "secret": "",
  "expirationDate": "2023-05-28T12:45:46Z"
}

Important: The newly created API key corresponds to the “secret” value. Please be aware that you need to grab the value of the API key as soon as you get the endpoint response. There is no way to retrieve the value of an existing API key. Please keep it safe and secure!

List the API Keys Associated to a User

You can list the API keys associated to a user by using the following endpoint:

API Endpointhttps://authenticate.foundation.api.oneatlas.airbus.com/api/v1/apikeys
REST verbGET
AuthenticationJWT Token
API ReferenceAPIKeys API

Below is an example to retrieve an access token using the API key with a cURL request:

curl -X GET \
  https://authenticate.foundation.api.oneatlas.airbus.com/api/v1/apikeys \
  -H "Authorization: Bearer <access_token>" \
  -H "Cache-Control: no-cache"'
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://authenticate.foundation.api.oneatlas.airbus.com/api/v1/apikeys");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);
import requests

url = "https://authenticate.foundation.api.oneatlas.airbus.com/api/v1/apikeys"

headers = {
    'Authorization': "Bearer",
    'Cache-Control': "no-cache",
    }

response = requests.request("GET", url, headers=headers)

print(response.text)

In this case, the user has two API keys: the first one is the initial API Key that was used to create the access token; the second one was just created.

{
  "items": [
    {
      "id": "<uid>",
      "description": "Initial API key.",
      "expirationDate": "2023-05-16T11:46:04Z"
    },
    {
      "id": "<uid>",
      "description": "New API key for GIS tools",
      "expirationDate": "2023-05-28T12:45:46Z"
    }
  ]
}

Test an API Key

The endpoint to test an API key associated to a user is described in the following table:

API Endpointhttps://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token
REST verbPOST
AuthenticationJWT Token
API ReferenceAuthentication API

Below is an example to retrieve an access token using the API key with a cURL request:

curl -X POST "https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token" \
   -H "Content-Type: application/x-www-form-urlencoded" \
   -H "Cache-Control: no-cache" \
   -d 'grant_type=api_key&client_id=AAA&apikey=<api_key_to_be_tested>'
var data = "grant_type=api_key&client_id=AAA&apikey=%3Capi_key_to_be_tested%3E";

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token/auth/realms/IDP/protocol/openid-connect/token");
xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);
import requests

url = "https://authenticate.foundation.api.oneatlas.airbus.com/auth/realms/IDP/protocol/openid-connect/token/auth/realms/IDP/protocol/openid-connect/token"

payload = "grant_type=api_key&client_id=AAA&apikey=<api_key_to_be_tested>"
headers = {
    'Content-Type': "application/x-www-form-urlencoded",
    'Cache-Control': "no-cache",
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

If the API key is valid, the result will be:

{
  "access_token": "XXXXXXXXX",
  "expires_in": 3600,
  "refresh_expires_in": 0,
  "token_type": "bearer"
}

However, if the API key is not valid, an error code 403 is provided:

{
  "error": "access_denied",
  "error_description": "Access denied"
}

Delete an API Key

If your key is no longer needed, you can delete it by using the DELETE API key request. The endpoint to delete an API key associated to a user is described in the following table:

API Endpointhttps://authenticate.foundation.api.oneatlas.airbus.com/api/v1/apikeys
REST verbDELETE
AuthenticationJWT Token
API ReferenceAPIKeys API

Below is an example to retrieve an access token using the API key thanks to a curl request:

curl -X DELETE "https://authenticate.foundation.api.oneatlas.airbus.com/api/v1/apikeys/<uid_of_api_key_to_delete>" \
   -H "Authorization: Bearer <access_token>" \
   -H "Cache-Control: no-cache"
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = false;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://authenticate.foundation.api.oneatlas.airbus.com/api/v1/apikeys/<uid_of_api_key_to_delete>");
xhr.setRequestHeader("Authorization", "Bearer <access_token>");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);
import requests

url = "http://https://authenticate.foundation.api.oneatlas.airbus.com/api/v1/apikeys/<uid_of_api_key_to_delete>"

headers = {
    'Authorization': "Bearer <access_token>",
    'Cache-Control': "no-cache",
    }

response = requests.request("DELETE", url, headers=headers)

print(response.text)

In case of success, a code 200 is returned.

Important: For security reasons, the response does not give any information regarding the effective deletion of the API key. To verify this, the endpoint used to list the API keys associated to a user should be used.

Contact Us