Authentication

On the ICEYE API Platform, authentication consists of sending credentials to a Token endpoint, which returns a temporary access token that is used to authorize API requests during a user session.

What you need for authentication

If your company has signed-up with ICEYE and already enabled access to the API Platform, you should have the following access details for authenticating on the API Platform (required for the Client Credentials flow):

Variable Description

Variable	Description
`TOKEN_URL`	The URL for the Token endpoint, which provides the authentication service for the API Platform
`CLIENT_ID`	OAuth2 client ID, which uniquely identifies the client app on the authorization server
`CLIENT_SECRET`	OAuth2 client secret, which is needed to authenticate the client app on the authorization server
`BASE64_KEY`	Base64-encoded value of `clientid:clientsecret`, which you must generate yourself

TOKEN_URL

The URL for the Token endpoint, which provides the authentication service for the API Platform

CLIENT_ID

OAuth2 client ID, which uniquely identifies the client app on the authorization server

CLIENT_SECRET

OAuth2 client secret, which is needed to authenticate the client app on the authorization server

BASE64_KEY

Base64-encoded value of clientid:clientsecret, which you must generate yourself

Generate the Base64 key

To generate the BASE64_KEY from the provided CLIENT_ID and CLIENT_SECRET values:

Linux or UNIX OS
Windows OS

Open a command prompt (in a Linux or UNIX OS) and set the following environment variables for the CLIENT_ID and CLIENT_SECRET:
```
 export CLIENT_ID="XXXXXXXXXX"
 export CLIENT_SECRET="XXXXXXXXXX"
```
Enter the following command to generate the Base64-encoded value of clientid:clientsecret:
```
 echo -n ${CLIENT_ID}:${CLIENT_SECRET} | base64
```
Copy the returned Base64-encoded value (BASE64_KEY) and store it in a safe place.

Open a Powershell command prompt and enter the following command to generate the Base64-encoded value of clientid:clientsecret:
```
[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("clientid:clientsecret"))
```
Copy the returned Base64-encoded value (BASE64_KEY) and store it in a safe place.

Access token

When you send an authentication request to the Token endpoint, a successful response contains an access token, which is a temporary token (typically valid for up to 1 hour) that is used to authorize API requests during the user session.

To authorize subsequent API requests, include the access token in each API request as a HTTP bearer token in the HTTP Authorization header.

If the access token is invalid or expired, the endpoint responds with a 403 error.

Client Credentials flow

To obtain an access token using the Client Credentials flow, make a POST request to the Token endpoint at TOKEN_URL.

Request

Enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

curl --request POST \
  --url "${TOKEN_URL}" \
  --header "Accept: application/json, application/problem+json" \
  --header "Authorization: Basic ${BASE64_KEY}" \
  --header "Cache-Control: no-cache" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials"

Response

If authentication is successful, the response is a JSON object containing the access token in its access_token property.

{
  "token_type":"Bearer",
  "expires_in":3600,
  "access_token":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "scope": "catalog.read deliveries.read orders.read activities.read contracts.read bundles.read internal_options.read customers.read internal_options.write"
}

The expires_in property indicates how long the access token is valid, in units of seconds. An API client could use this information to automatically refresh the token before it expires.

Resource Owner Password flow

If you signed up to the ICEYE API Platform before July 2024, you might still be using the Resource Owner Password flow. With this procedure, authentication is tied to a specific user account and requires you to provide user credentials (username and password) when requesting an access token.

To authenticate on the API Platform using the Resource Owner Password flow:

On a Linux or UNIX platform, set the following environment variables, using the values from your access details (provided by the COSP team):
```
 export API_USERNAME="XXXXXXXXXX"
 export API_PASSWORD="XXXXXXXXXX"
 export TOKEN_URL="XXXXXXXXXX"
 export API_KEY="XXXXXXXXXX"
```

Send a request to the Token endpoint to obtain an access token:

 curl --location --request POST "${TOKEN_URL}" \
 --header "Authorization: Basic ${API_KEY}" \
 --header "Content-Type: application/x-www-form-urlencoded" \
 --data-urlencode "grant_type=password" \
 --data-urlencode "username=${API_USERNAME}" \
 --data-urlencode "password=${API_PASSWORD}"

If the request is successful, you should receive a response like the following:

 {
   "token_type":"Bearer",
   "expires_in":3600,
   "access_token":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
 }