Authentication

The Atrope API uses Auth0 to issue JWTs. Every request must carry a signed Bearer token. All data is scoped to the tenant encoded in the token — one token can never access another tenant’s data.

Getting a token

Obtain a token from your Auth0 tenant using the standard OAuth 2.0 Client Credentials or Authorization Code flow, depending on whether you’re building a server-to-server integration or a user-facing application.

curl --request POST \
  --url https://YOUR_AUTH0_DOMAIN/oauth/token \
  --header "Content-Type: application/json" \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "YOUR_API_AUDIENCE",
    "grant_type": "client_credentials"
  }'

The response includes an access_token. Use it on every subsequent request.

Sending the token

Pass the token in the Authorization header:

Authorization: Bearer <access_token>

With the SDK — inject via the fetcher option:

import { createImsApiClient } from "@atrope-ai/api-client";

const ims = createImsApiClient({
  baseUrl: "https://api.atrope.dev",
  fetcher: (url, init) =>
    fetch(url, {
      ...init,
      headers: {
        ...init?.headers,
        Authorization: `Bearer ${accessToken}`,
      },
    }),
});

With direct HTTP:

curl https://api.atrope.dev/v1/items \
  -H "Authorization: Bearer <access_token>"

Token claims

The API reads the following custom claims from your JWT. These are set by your Auth0 rule or action:

The claim namespace prefix (https://atrope.dev/claims/) is configurable per deployment.

Tenant isolation

Every API response is filtered by the tenant in your token. There is no way to query across tenants. If you manage multiple tenants, issue a separate token per tenant and create a separate SDK client instance for each.

Permissions

Permissions are scoped actions encoded in the token. The API enforces them per endpoint. Common permissions:

Local development

When AUTH_MODE=dev, the API does not validate tokens. Any request is accepted and attributed to the configured dev tenant and user. This mode is only available when AUTH0_ISSUER_URL and AUTH0_AUDIENCE are not set.

Never run AUTH_MODE=dev in production.