Skip to content

Aleph API Authentication

1. Are you an Aleph user already?

Access to the Aleph API is exclusively available to registered users of the Aleph platform. To use our API services:

  • Existing Users: If you already have an Aleph account, you can proceed to create API credentials through your account profile.
  • New Users: If you don't have access to Aleph yet, please contact our sales team at sales@satellogic.com to discuss your needs and set up your account.

2. Key Concepts

Understanding these concepts will help you navigate authentication with Aleph:

Contracts

In Aleph, a Contract is the legal framework that defines the conditions under which a user, with access to that contract, can interact with our available products—such as Archive Imagery or Tasking.

Here's what you need to know:

  • Contracts define the specific products and services your organization can access
  • Each API credential is associated with a specific contract
  • Contracts determine:
  • Which products you can order (e.g., imagery products)
  • The level of access to our archives
  • Your tasking capabilities
  • Delivery options available to you

Roles

Different roles in Aleph grant access to different features and capabilities.

To create an API credential, your user account must have the Imagery User role. This role allows you to access and interact with Aleph's geospatial data through the API and the GUI.

API Credentials to use geospatial data has a different role called M2M Imagery Intergrator.

M2M Imagery Integrator

  • The most common role for API access
  • Designed for automated, machine-to-machine operations
  • Allows programmatic access to order and retrieve imagery products

3. How to Create an API Credential

API credentials allow applications to authenticate and interact with Aleph's API. Follow these steps to generate your credentials:

Step 1: Log into Aleph

  • Visit Aleph's web interface at https://aleph.satellogic.com/
  • Enter your username and password.
  • Ensure your account has the necessary permissions to create API credentials.

Step 2: Access Your Profile

  • Click on the menu icon in the top-left corner of the screen.
  • From the menu, select "My Profile" at the bottom left.

Aleph Auth 1

Step 3: Create New Credentials**

  • Click the "Create New API Credential" button

  • Fill in the required information:

    • Name: Choose a descriptive name for these credentials
    • Role: Select the appropriate role (typically "M2M Imagery Integrator")
    • Contract: Choose one or more contracts the new credential will be associated with

Aleph Auth 2

Step 4: Save Your Credentials**

  • After creation, you'll receive a Client ID and Client Secret
  • ⚠️ Important: Copy and securely store both the Client ID and Client Secret
  • These credentials cannot be retrieved later - if lost, you'll need to create new ones

Managing Credentials

  • If you need to change the contract or role, you must create new credentials
  • Lost credentials cannot be recovered and must be replaced with new ones
  • You can have multiple active credentials for different purposes

Using Your API Credentials

Authentication Flow

Aleph API implements the OAuth 2.0 standard for authentication, specifically using the Client Credentials flow. This ensures secure access to our API endpoints while maintaining industry-standard security practices.

The authentication process consists of two main steps: 1. Obtaining an access token using your API credentials 2. Verifying and selecting the contract you want to operate with

Step 1: Obtaining an Access Token

Obtaining an Access Token

First, exchange your API credentials for an access token:

curl --location --request POST 'https://auth.platform.satellogic.com/oauth/token'     --header 'content-type: application/json'     --data-raw '{
    "client_id": "<API_CREDENTIAL_ID>", 
    "client_secret": "<API_CREDENTIAL_SECRET>",
    "audience": "https://api.satellogic.com/",
    "grant_type": "client_credentials"
}'

The response includes an access token that will be valid for 24 hours:

{
    "access_token": "<ACCESS_TOKEN>",
    "scope": "api:tasking api:delivery",
    "expires_in": 86400,
    "token_type": "Bearer"
}

You can use this token for multiple requests until it expires. After expiration, you'll need to request a new token.

Step 2: Verifying Available Contracts

Listing available contracts for an API Credential

Once you have an access token, verify the contracts associated with your API credentials:

curl --location --request GET 'https://api.satellogic.com/contracts' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>'

The response will list all contracts available to your credentials:

[
    {
        "contract_id": "contract-123",
        "name": "Enterprise Imagery Access",
    }
]

Step 3: Making API Requests

⚠️ IMPORTANT: All API requests require both: - The access token in the authorizationToken header - The contract ID in the X-Satellogic-Contract-Id header

Failing to provide either will result in an unauthorized response.

The only endpoint that can be used without the X-Satellogic-Contract-Id header is /contracts.

Requesting Tasking Products 
curl --location --request GET 'https://api.satellogic.com/tasking/products' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>' \
--header 'X-Satellogic-Contract-Id: contract-123'
Searching Archive Products 
curl --location --request POST 'https://api.satellogic.com/archive/search' \
--header 'authorizationToken: Bearer <ACCESS_TOKEN>' \
--header 'X-Satellogic-Contract-Id: contract-123' \
--header 'Content-Type: application/json' \
--data-raw '{
    "bbox": [-122.4, 37.7, -122.3, 37.8],
    "start_date": "2024-01-01",
    "end_date": "2024-02-01"
}'

Python Example

import requests
import json

# 0. Complete the following section with your client id and secret
client_id = ""
client_secret = ""

# 1. Get the access token for your API Credentials

access_token_url = "https://auth.platform.satellogic.com/oauth/token"
payload = json.dumps({
    "client_id": client_id,
    "client_secret": client_secret,
    "audience": "https://api.satellogic.com/",
    "grant_type": "client_credentials"
})
headers = {
    'Content-Type': 'application/json'
}

access_token_response = requests.post(access_token_url, headers=headers, data=payload)
access_token_response.raise_for_status()
access_token = access_token_response.json().get('access_token')


# 2. Get your contracts. 

ALEPH_API_URL = "https://api.satellogic.com"
contracts_uri = "/contracts/"

contracts_response = requests.get(
    f"{ALEPH_API_URL}{contracts_uri}", 
    headers={
        'AuthorizationToken': f'Bearer {access_token}',
    })
contracts_response.raise_for_status()
contracts = contracts_response.json()

print("Your contracts are: ")
print(contracts)

# 4. Save the contract_id for future requests
# For this example we will use the first available contracts, but there can me many.
your_contract_id = contracts[0]['contract_id']

# 3. List your tasks for tasking imagery
tasks_uri = "/tasking/tasks/"

tasks_response = requests.get(
    f"{ALEPH_API_URL}{tasks_uri}", 
    headers={
        'AuthorizationToken': f'Bearer {access_token}',
        'X-Satellogic-Contract-Id': your_contract_id,
    },
)
tasks_response.raise_for_status()
tasks = tasks_response.json()

print("Your tasks are: ")
print(tasks)


# 4. List your available stac collections for archive imagery
stac_collections_uri = "/archive/stac/collections/"

stac_response = requests.get(
    f"{ALEPH_API_URL}{stac_collections_uri}", 
    headers={
        'AuthorizationToken': f'Bearer {access_token}',
        'X-Satellogic-Contract-Id': your_contract_id,
    },
)
stac_response.raise_for_status()
stac_collections = stac_response.json()

print("Your available STAC collections are: ")
print(stac_collections)