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:
-
Exchange credentials once: Send your
CLIENT_IDandCLIENT_SECRETto get an access token -
Use the token: Include the token in your API requests
-
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.
Credentials
ICEYE provides these credentials during onboarding:
| Credential | Description |
|---|---|
|
Authentication endpoint URL |
|
Your unique client identifier |
|
Your secret key (keep this secure!) |
|
Never commit your |
Token endpoint
Request
Method |
|
URL |
Your |
Content-Type |
|
Headers:
| Header | Value |
|---|---|
|
|
|
|
|
|
Body Parameters:
| Parameter | Required | Description |
|---|---|---|
|
Yes |
Must be |
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 |
|---|---|---|
|
string |
Your authentication token (use in API requests) |
|
string |
Always "Bearer" |
|
integer |
Token lifetime in seconds (typically 3600) |
|
string |
Space-separated list of permissions |
Error Responses:
| Status Code | Description |
|---|---|
|
Invalid request (missing or invalid |
|
Invalid credentials (incorrect |
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 |
For production applications that need automatic token management, see the Token Management How-To Guide.