Authenticating with an API Key

The ReelStorage public API lets your own systems work inside your projects without a browser: ingest from a camera cart, write captions from a DAM, pull selects into a delivery pipeline. Every request is authenticated with an organization API key. This guide covers creating one and using it. The full endpoint list is in the API reference.

What You'll Learn

• Who can create an API key and where
• How to send the key with a request
• What a key is allowed to do, and why
• When a key stops working

Step 1: Create a Key

Open Organization → Settings → API keys. Only an organization owner sees this page; admins and members do not. Click Create key, give it a name that says what system will use it ("Ingest from cart 2", not "test"), pick a purpose preset or choose scopes by hand, and set an expiry. Ninety days is the default; thirty days, one year, and never are available.

The key is shown once. Copy it into your secret store before closing the dialog. ReelStorage cannot show it again, so a lost key must be replaced, not recovered.

Step 2: Send the Key

Put the key in an x-api-key header on every request. There is no bearer token and no query parameter form.

curl https://reelstorage.com/api/v1/projects/PROJECT_ID/assets \
  --header "x-api-key: $REELSTORAGE_API_KEY"

All request and response bodies are JSON. Timestamps are ISO 8601 strings in UTC. Ids are opaque strings; never parse them.

Step 3: Understand What the Key Can Do

A key is not a separate user. It acts as the owner who created it, inside the projects that owner can access, with that owner's permissions in each project narrowed by the key's scopes. Two consequences follow:

• A key can never do more than its creator. Scopes only remove permissions; they cannot add one the creator does not have. See Scopes.
• A key cannot administer a project. Changing settings, inviting or removing members, editing permissions, and deleting a project are never available to a key, whatever scopes it holds.

The API is also strictly project-scoped. Every route lives under /api/v1/projects/{projectId}/…. There is no "list my projects" call in v1; your integration is configured with the project ids it works in.

When a Key Stops Working

• Expiry. A key past its expiry date is rejected with 401.
• Revocation. Any owner can revoke a key on the API keys page. The next request gets 401.
• The creator leaves. Because the key acts as its creator, it dies when that person is removed from the organization. The API keys page flags these keys so you can replace them.
• The plan changes to free. Keys work on paid plans only. After a downgrade every key gets 401 until the organization upgrades again; the keys themselves are kept.
• Rate limit. Each key may make 600 requests per minute. Over that, requests are rejected with 429 and a Retry-After header; wait that many seconds, then retry.

Troubleshooting

I get 403 on a project I can open in the app

The key's creator must be a member of that project, and the key must hold a scope that covers the operation. Check the project's members list for the creator, then the key's scopes on the API keys page. A missing scope says Missing permission: <scope>. A project that does not exist and one not shared with the creator both say Access denied; the API does not say which.

I get 404 for an asset I can see in the app

Hidden assets are invisible to a key unless it holds the viewHiddenAssets scope, and a key whose creator can only see published assets will not find drafts. Both cases return the same 404 as a truly missing asset. See Errors.

What's Next

• Scopes: the full list of what a key can be allowed to do
• Uploading Files: the three-step upload protocol
• API reference: every endpoint with a live request panel