Authentication

Every Raster REST request is authenticated with an API key and pinned to a specific API version. Both are sent as HTTP headers — there is no /v1 URL segment, no client SDK to install.

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 401 and API_KEY_NOT_AUTHORIZED_FOR_LIBRARY.

The Authorization header

Send your key as a bearer token:

Authorization: Bearer pk_4eC39HqLH3U46nipzJ6ixhzdp7dc42Sf

A missing or malformed Authorization header rejects the request with 401 and API_KEY_NOT_PROVIDED — the data layer is never reached.

The Api-Version header

REST uses per-request header versioning instead of a URL segment like /v1. 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 — also before the data layer is reached.

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/monogram-labs/libraries'

Requirements

• HTTPS only. Requests over plain HTTP are rejected.
• API key required. Requests without a valid Authorization: Bearer are rejected with 401.
• 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.