Authentication

Every request to the Raster API is authenticated with an API key or an OAuth access token. A key belongs to one organization and can be scoped to the libraries you choose.

API keys

An API key lets external applications reach the libraries you permit through the Raster API. You manage keys in each organization's settings, where you can:

Create a key when you need one.
Scope it to specific libraries.
Regenerate it if it is ever exposed.
Delete it when it is no longer needed.

Creating a key

Open organization settings

Go to Organization name → Settings in the Raster app.

Generate a new key

In the API keys section, generate a new key and copy it. You can reveal and copy it again later from the same section.

Grant library access

Enable Read access for every library the key should reach. Add Write access if the key will run any mutation. Save your changes.

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 has an access level for each library. Every operation checks that level before it runs:

Level	Grants
Read	Run queries, such as `assets`, `libraries` and `tags`.
Write	Run every mutation, such as `uploadAssets` and `deleteAssets`. Includes read.

A request that targets a library the key cannot reach fails with an API_KEY_NOT_AUTHORIZED_FOR_LIBRARY error.

Authenticating a request

Send your key as a bearer token in the Authorization header:

Authorization: Bearer <API_KEY>

A complete request looks like this:

Terminal

curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <API_KEY>' \
  --url 'https://api.raster.app/' \
  --data '{"query": "query { libraries(organizationId: \"acme-co\") { id name } }"}'

Requirements

Requests must use HTTPS. Plain HTTP requests are rejected.
Requests must carry a valid API key or OAuth access token. Requests without one are rejected.
The key must have the right access level for every library a request touches.

On this page