Authentication
Authenticate REST requests with an API key or an OAuth access token, and declare the API version.
Every Raster REST request is authenticated with an API key or an OAuth access token and declares the API version it was written against. Both are sent as HTTP headers.
API keys
Keys belong to an organization and are managed in its settings. To create one:
- In Organization settings → API keys, generate a new key.
- Enable Read access for every library the key should reach. Add Write access if the key will call any Write endpoint (see Access levels).
- Copy the key.
Delete a key in the same place when it is no longer needed.
Treat API keys like passwords. Never commit them to source control or expose them in client-side code. If a key leaks, regenerate it immediately; the old value stops working at once.
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 gets.
The Authorization header
Send your API key or OAuth access token as a bearer token:
Authorization: Bearer <API_KEY>A missing or malformed Authorization header rejects the request with 401
and UNAUTHENTICATED. An API key unknown
to the target organization returns 401 INVALID_API_KEY.
An OAuth access token that is invalid, expired, or revoked returns 401
UNAUTHENTICATED. When an access token
cannot be verified for a moment, the request returns 503
SERVICE_UNAVAILABLE; retry it with
backoff.
POST /libraries is anonymous. It creates
a new API key, so it needs no Authorization header.
The Api-Version header
Every request must declare the API version it was written against:
Api-Version: 2026-07-08The current version is 2026-07-08. 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. During the Alpha, every Api-Version value
receives the current behavior, so a breaking change reaches every integration.
A complete request
A full authenticated REST request looks like this:
curl --request GET \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Api-Version: 2026-07-08' \
--url 'https://api.raster.app/organizations/acme-co/libraries'Requirements
Requests must use HTTPS; plain HTTP is rejected. A request without a valid
Authorization: Bearer header is rejected with 401, except the anonymous
POST /libraries endpoint, which creates
a key. A request without a non-empty Api-Version header is rejected with
400. The API key, or the OAuth access token's account, must have the right
access to every library the request touches.