Authentication

Every Raster REST request is authenticated with an API key and pinned to a specific API version. Both are sent as HTTP headers.

API keys

REST and GraphQL share the same key system: a key created in your organization settings works for both APIs, with the same per-library access levels.

To create, scope, regenerate, or revoke a key, follow the full walkthrough in GraphQL Authentication → API keys. The short version:

1. In Organization settings → API keys, generate a new key.
2. Enable Read access for every library the key should reach. Add Write access if the key will upload or delete assets.
3. Copy the key once — it is shown only at creation.

Access levels

Each key carries a per-library access level. Every endpoint checks the level before running:

A request that targets a library the key cannot reach fails with 404 and API_KEY_NOT_AUTHORIZED_FOR_LIBRARY — the same response a request for a library that does not exist would get. The status is deliberately 404, not 403, so a key without access cannot probe library existence by comparing error codes. See Errors for the full rationale.

The Authorization header

Send your key as a bearer token:

Authorization: Bearer <API_KEY>

A missing or malformed Authorization header rejects the request with 401 and UNAUTHENTICATED. An Authorization header that is present but carries a token unknown to the target organization returns 401 INVALID_API_KEY instead.

The Api-Version header

Every request must declare the API version it was written against:

Api-Version: 2026-05-20

The current version is 2026-05-20. A missing or empty Api-Version header rejects the request with 400 and API_VERSION_REQUIRED.

Every response carries Vary: Api-Version, so HTTP caches (your CDN, browser, intermediaries) key bodies per version. Two clients on different versions never see each other's response bodies.

When a breaking change ships, the new value goes in the changelog. Existing integrations keep working against their pinned version until they choose to migrate.

A complete request

A full authenticated REST request looks like this:

curl --request GET \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Api-Version: 2026-05-20' \
  --url 'https://api.raster.app/organizations/acme-co/libraries'

Requirements

• HTTPS only. Requests over plain HTTP are rejected.
• API key required. Requests without a valid Authorization: Bearer are rejected with 401 — except the anonymous POST /libraries endpoint, which mints a key.
• Api-Version required. Requests without a non-empty Api-Version header are rejected with 400.
• Scope matters. The key must have the right access level for every library it touches.