Authentication

All API requests require authentication using API keys scoped to a tenant within your organization. This page covers how to obtain credentials, authenticate requests, and manage your keys.

Getting Your Credentials

Create API keys in the Dashboard Portal under your tenant settings. Each key is scoped to a specific tenant within your organization, which means it automatically determines the data, rate limits, and policies that apply to your requests. When creating a key you choose one of two types — Secret or Publishable — and select the target environment. You can create separate keys for each environment and type.

Your API key implicitly carries both the tenant and organization context, so you never need to specify these IDs in your requests. For a detailed explanation of the tenant and organization hierarchy, see Core Concepts.

API Key Types

The Adapt2Move API supports two key types designed for different runtime contexts.

Use secret keys whenever your code runs on a server you control — backend services, cron jobs, server-side rendering. Use publishable keys when you need to call the API directly from a browser, for example to power a map with live mobility data, a search widget, or an availability display.

Publishable Keys

Publishable keys are purpose-built for client-side use. They grant read-only access to a limited set of endpoints, so even if a key is extracted from your frontend source code, it cannot be used to create bookings or modify any data.

The allowed permissions are:

• cars:offer:read
• micromobility:offer:read
• public-transport:offer:read
• providers:read
• multimodal:explore:read

Domain Configuration

Every publishable key must be configured with one or more allowed domains in the Dashboard Portal. The API validates the Origin header on each request and rejects any origin that does not match. You can specify exact domains such as app.example.com or wildcard patterns such as *.example.com. Localhost origins are automatically allowed in non-production environments so you can develop without additional configuration.

Browser Usage

const response = await fetch("https://adapt2move.de/mobility-api/v2/micromobility/offers", {
  headers: {
    Authorization: "Bearer a2m_pk_live_YOUR_PUBLISHABLE_KEY",
  },
});
const offers = await response.json();

The API returns automatic CORS headers for publishable key requests, so standard browser fetch calls work without a proxy.

Making Authenticated Requests

Every API request must include your API key in one of two headers: Authorization: Bearer <api_key> (standard Bearer token) or x-api-key: <api_key> (alternative header). Both methods are equivalent and identify your tenant and organization automatically.

curl -X POST https://adapt2move.de/mobility-api/v2/cars \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup": {
      "type": "coordinates",
      "coordinates": {
        "latitude": 52.520008,
        "longitude": 13.404954
      }
    },
    "dates": {
      "start": "2026-12-01T10:00:00Z",
      "end": "2026-12-05T10:00:00Z"
    }
  }'

Common Mistakes

The most frequent authentication error is omitting the Bearer prefix from the Authorization header. Writing Authorization: YOUR_API_TOKEN instead of Authorization: Bearer YOUR_API_TOKEN will result in a 401 error. Similarly, never pass your API key as a URL query parameter — tokens in URLs end up in server logs, browser history, and proxy logs, creating a significant security risk. Always transmit credentials exclusively through request headers.

Authentication Flow

When you send a request, the gateway validates your API key and resolves the associated tenant and organization. For secret keys, the request proceeds immediately with the correct context. For publishable keys, the gateway additionally validates the Origin header against the key's allowed domains and returns a 403 error if the origin is not permitted. If the key itself is invalid, you receive a 401 error.

Key Management

You create, rotate, and revoke API keys in the Dashboard Portal. If a key is compromised, revoke it immediately in the Dashboard Portal or contact info@adapt2move.de for urgent assistance.

Common Authentication Errors

See Error Handling for complete error documentation, or explore all endpoints in the interactive OpenAPI Reference.