API authentication

API authentication

All GEM API requests require authentication using two methods: a TomTom API key and an authorization token. This page explains how to obtain and use both.

Authentication overview

Every API request must include these headers:

Example request with authentication:

1curl -X GET "https://api.tomtom.com/maps/orbis/platform/private-gateway/storages" \
2  -H "tomtom-api-key: YOUR_API_KEY" \
3  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Obtaining a TomTom API key

Step 1: Access the key management portal

1. Navigate to my.tomtom.com and log in
2. In the left navigation menu, click Keys
3. Select API & SDK Keys from the submenu

Step 2: Create a new API key

1. Click the Create Key button in the top right corner
2. Enter a descriptive name for your key (e.g., "GEM API Integration")
3. Important: Select both required API products:
   • Orbis Private Data Gateway API
   • Orbis GEM API
4. Click Create to generate the key

Step 3: Copy your API key

Once created, your new key appears in the list of available keys. Copy the key value—you'll use this as the tomtom-api-key header in all API requests.

For detailed information about API key management, see the API Key Management documentation.

Security best practices:

• Keep your API key confidential
• Don't commit API keys to version control
• Use environment variables to store keys in applications
• Rotate keys periodically
• Create separate keys for different environments (development, staging, production)

Obtaining an authorization token

The authorization token authenticates your identity using Azure Active Directory. You'll need the Azure CLI installed to generate this token.

Prerequisites

Install Azure CLI on your system:

macOS:

brew install azure-cli

Windows:

Download and run the installer from the Azure CLI installation page.

Linux (Debian/Ubuntu):

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Step 1: Log in to Azure

First, authenticate with Azure:

az login

This opens a browser window for you to complete the authentication flow. Once authenticated, you'll see confirmation in your terminal.

Step 2: Generate the access token

Request an access token scoped to the GEM service:

az account get-access-token --scope https://gem.core.orbis.tomtom.com/user_impersonation

Example response:

1{
2  "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6...",
3  "expiresOn": "2026-01-26 12:01:55.000000",
4  "expires_on": 1769425315,
5  "subscription": "bb..84",
6  "tenant": "374f8026-7b54-4a3a-b87d-328fa26ec10d",
7  "tokenType": "Bearer"
8}

Step 3: Use the token

Extract the accessToken value from the response and use it in the Authorization header:

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6..."

Token expiration

Authorization tokens have a limited lifespan (typically 1 hour). When a token expires:

1. API requests will return 401 Unauthorized
2. Generate a new token using the same az account get-access-token command
3. Update your requests with the new token

Tip: For automated scripts, check the expiresOn field and refresh the token before it expires.

Complete authentication example

Here's a complete example showing how to authenticate and make an API request:

1#!/bin/bash
2
3# Set your TomTom API key
4TOMTOM_API_KEY="your-api-key-here"
5
6# Log in to Azure (interactive, do this once)
7az login
8
9# Get authorization token
10TOKEN_RESPONSE=$(az account get-access-token --scope https://gem.core.orbis.tomtom.com/user_impersonation)
11AUTH_TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.accessToken')
12
13# Make an API request
14curl -X GET "https://api.tomtom.com/maps/orbis/platform/private-gateway/storages" \
15  -H "tomtom-api-key: $TOMTOM_API_KEY" \
16  -H "Authorization: Bearer $AUTH_TOKEN"

Storing credentials securely

Using environment variables

Store your API key in environment variables:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export TOMTOM_API_KEY="your-api-key-here"

Then reference it in scripts:

1curl -X GET "https://api.tomtom.com/maps/orbis/platform/private-gateway/storages" \
2  -H "tomtom-api-key: $TOMTOM_API_KEY" \
3  -H "Authorization: Bearer $AUTH_TOKEN"

Using a credentials file

For applications, consider using a configuration file that's excluded from version control:

# credentials.env (add to .gitignore)
TOMTOM_API_KEY=your-api-key-here

Load credentials in your script:

source credentials.env

Error responses

Authentication errors

Example error response

1{
2  "error": {
3    "code": "Unauthorized",
4    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
5  }
6}

Next steps

• Private Data Gateway API - Learn how to manage storage
• GEM API - Create and manage matching jobs