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.


Every OneAtlas account has an API key. If you do not have a OneAtlas account, register here.
To get your API key, 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 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 service you want to get access. If you want to get access to the One Atlas services, then use the “IDP” value. However, if you want to get access to the API key management services, then use the “AAA” value.

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

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 suspend automatically the authorization to access to the API for a limited period of time. In such case, the user will receive a 403 error code, 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 an authentication by a JWT token. Please note that this token must be generated using an existing API key and the procedure described in the previous paragraph. Also, note that the “client_id” parameter must have the value “AAA”

Create Additional API Keys for a User

The endpoint to use 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 using 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 belongs 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’s no chance to provide again the value of an existing API key value. 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 using 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 belongs two API keys, the first one which is the initial one that was used to create the JWT token and the second one that 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 use 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 using 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 use 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

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