Authentication

New to ICEYE? Start with the Quickstart guide to make your first API call in 5 minutes.

Overview

The ICEYE Constellation API Suite (ICAS) uses OAuth 2.0 Client Credentials flow for authentication. This guide provides technical details about how authentication works.

What is OAuth 2.0?

OAuth 2.0 is an industry-standard authorization framework used by most modern APIs. Instead of sending your credentials with every API request, OAuth 2.0 uses access tokens:

  1. Exchange credentials once: Send your CLIENT_ID and CLIENT_SECRET to get an access token

  2. Use the token: Include the token in your API requests

  3. Access token expires: After 1 hour, request a new access token

This approach is more secure than sending credentials with every request. Your CLIENT_ID and CLIENT_SECRET stay secure on your backend, while access tokens can be used in frontend applications with lower risk. If an access token is compromised, it expires automatically and your credentials remain safe.

How it works

Authentication follows this flow:

  1. Get credentials from ICEYE (TOKEN_URL, CLIENT_ID, CLIENT_SECRET)

  2. Request an access token by exchanging your credentials

  3. Include the access token in all API requests

  4. Request a new access token before the current one expires (access tokens last 1 hour)

Authentication Flow

Credentials

ICEYE provides these credentials during onboarding:

Credential Description

TOKEN_URL

Authentication endpoint URL

CLIENT_ID

Your unique client identifier

CLIENT_SECRET

Your secret key (keep this secure!)

Never commit your CLIENT_SECRET to version control or share it publicly. Use environment variables or a secrets manager.

Token endpoint

Request

Method

POST

URL

Your TOKEN_URL (provided by ICEYE)

Content-Type

application/x-www-form-urlencoded

Headers:

Header Value

Authorization

Basic {BASE64_KEY} where BASE64_KEY is base64-encoded CLIENT_ID:CLIENT_SECRET

Content-Type

application/x-www-form-urlencoded

Accept

application/json

Body Parameters:

Parameter Required Description

grant_type

Yes

Must be client_credentials

Response

Success (200 OK):

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "catalog.read deliveries.read orders.read activities.read contracts.read bundles.read"
}
Field Type Description

access_token

string

Your authentication token (use in API requests)

token_type

string

Always "Bearer"

expires_in

integer

Token lifetime in seconds (typically 3600)

scope

string

Space-separated list of permissions

Error Responses:

Status Code Description

400 Bad Request

Invalid request (missing or invalid grant_type)

401 Unauthorized

Invalid credentials (incorrect CLIENT_ID or CLIENT_SECRET)

Code examples

Request an access token using the OAuth 2.0 Client Credentials flow:

  • cURL

  • PowerShell

  • Python

  • JavaScript/Node.js

  • Java

curl --request POST \
  --url "${TOKEN_URL}" \
  --header "Authorization: Basic ${BASE64_KEY}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Accept: application/json" \
  --data "grant_type=client_credentials"
$CLIENT_ID = "your_client_id"
$CLIENT_SECRET = "your_client_secret"
$TOKEN_URL = "your_token_url"

# Generate BASE64_KEY
$BASE64_KEY = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("${CLIENT_ID}:${CLIENT_SECRET}"))

# Get access token
$response = Invoke-RestMethod -Uri $TOKEN_URL `
    -Method Post `
    -Headers @{
        "Authorization" = "Basic $BASE64_KEY"
        "Content-Type" = "application/x-www-form-urlencoded"
        "Accept" = "application/json"
    } `
    -Body "grant_type=client_credentials"

$accessToken = $response.access_token
Write-Host "Access token: $accessToken"
import base64
import requests

token_url = "your_token_url"
client_id = "your_client_id"
client_secret = "your_client_secret"

# Generate BASE64_KEY
credentials = f"{client_id}:{client_secret}"
base64_key = base64.b64encode(credentials.encode()).decode()

response = requests.post(
    token_url,
    headers={
        'Authorization': f'Basic {base64_key}',
        'Content-Type': 'application/x-www-form-urlencoded',
        'Accept': 'application/json'
    },
    data={'grant_type': 'client_credentials'}
)

token_data = response.json()
access_token = token_data['access_token']
print(f"Access token: {access_token}")
const axios = require('axios');

const tokenUrl = "your_token_url";
const clientId = "your_client_id";
const clientSecret = "your_client_secret";

// Generate BASE64_KEY
const base64Key = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

async function getAccessToken() {
  const response = await axios.post(
    tokenUrl,
    'grant_type=client_credentials',
    {
      headers: {
        'Authorization': `Basic ${base64Key}`,
        'Content-Type': 'application/x-www-form-urlencoded',
        'Accept': 'application/json'
      }
    }
  );
  
  return response.data.access_token;
}

(async () => {
  const token = await getAccessToken();
  console.log('Access token:', token);
})();
import java.net.http.*;
import java.net.URI;
import java.util.Base64;

public class IceyeAuth {
    public static void main(String[] args) throws Exception {
        String tokenUrl = "your_token_url";
        String clientId = "your_client_id";
        String clientSecret = "your_client_secret";
        
        // Generate BASE64_KEY
        String credentials = clientId + ":" + clientSecret;
        String base64Key = Base64.getEncoder().encodeToString(credentials.getBytes());
        
        // Build request
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(tokenUrl))
            .header("Authorization", "Basic " + base64Key)
            .header("Content-Type", "application/x-www-form-urlencoded")
            .header("Accept", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString("grant_type=client_credentials"))
            .build();
        
        // Send request
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        // Parse access_token from response
        String json = response.body();
        int start = json.indexOf("\"access_token\":\"") + 16;
        int end = json.indexOf("\"", start);
        String accessToken = json.substring(start, end);
        
        System.out.println("Access token: " + accessToken);
    }
}

Using the access token

Include the access token in the Authorization header of all API requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

curl --request GET \
  --url "https://platform.iceye.com/api/company/v1/contracts" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

Authentication methods

Client Credentials flow

The Client Credentials flow is the standard authentication method for ICAS. It’s designed for server-to-server communication.

Resource Owner Password Flow (Legacy - Deprecated)

Deprecated: This authentication method is being phased out. New integrations should use the Client Credentials flow.

If you signed up before July 2024, you might still be using the Resource Owner Password flow. This method requires username and password credentials.

To authenticate using this legacy method:

export API_USERNAME="your_username"
export API_PASSWORD="your_password"
export TOKEN_URL="your_token_url"
export API_KEY="your_base64_api_key"

curl --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}"

To migrate to Client Credentials flow, contact ICEYE support.

Token Expiration

Access tokens expire after 1 hour. When your token expires, simply request a new one using the same credentials.

The Client Credentials flow does not use refresh tokens. When your access token expires (you’ll receive a 401 error), request a new token using the same CLIENT_ID and CLIENT_SECRET.

For production applications that need automatic token management, see the Token Management How-To Guide.