Authentication

Every request to the Reelspan API carries an API key in the Authorization header. A key belongs to one workspace. You can limit what it may do (scopes), which profiles it may use, and when it stops working.

curl https://api.reelspan.com/v1/me \
  -H "Authorization: Bearer $REELSPAN_API_KEY"

import { Reelspan } from 'reelspan';

const reelspan = new Reelspan(); // reads REELSPAN_API_KEY
const me = await reelspan.me();

from reelspan import Reelspan

reelspan = Reelspan()  # reads REELSPAN_API_KEY
me = reelspan.me()

GET /v1/me is the quickest way to check a key: it answers 200 with your plan and usage, or 401. See Current account.

Create a key

Keys are created in the dashboard, under Developers → API keys. Only workspace owners and admins can create, rename or revoke them.

When you create a key you choose:

• Name: so you can tell your keys apart, for example n8n uploader.
• Test key: tick it for a rs_test_ key that never publishes (see Test keys).
• Access: everything, or only some scopes.
• Profiles: all profiles, or only some (shown when the workspace has more than one profile).
• Expires: never, in 30 days, in 90 days, or in a year.

A live key starts with rs_live_, a test key with rs_test_. The full key is shown once, when you create it. Reelspan stores only a SHA-256 hash of it, so a lost key can't be shown again: create a new one and revoke the old one.

The API keys page lists each key with its first characters, its scopes, when it was last used, how many posts it sent in the last 30 days, and when it expires.

Send the key

Put the key in the Authorization header with the Bearer scheme. The word Bearer is not case-sensitive.

Authorization: Bearer rs_live_…

The Apikey scheme works too, so code written for Upload-Post keeps working with only a new key:

Authorization: Apikey rs_live_…

Those are the only accepted forms. A key in a query string, in another header, or with any other scheme answers 401.

The SDKs read the key from the REELSPAN_API_KEY environment variable, or you pass it in:

const reelspan = new Reelspan({ apiKey: process.env.REELSPAN_API_KEY });

import os
from reelspan import Reelspan

reelspan = Reelspan(api_key=os.environ["REELSPAN_API_KEY"])

Use api.reelspan.com

API keys work only on the API host: https://api.reelspan.com/v1. The dashboard's address (app.reelspan.com) refuses them with 421 and error_code: USE_API_HOST, and the answer names the right address in api_url.

Scopes

A key can do only what its scopes allow. A key created with Everything has no scope list and can do it all. A call outside a key's scopes answers 403 with error_code: INSUFFICIENT_SCOPE.

When you untick Everything in the dashboard, every scope except webhooks starts ticked. GET /v1/me and GET /v1/preferences work with any key, whatever its scopes.

Keys limited to profiles

Give a key only some profiles, for example one key per client. Then:

• A call that names another profile answers 403 with error_code: PROFILE_FORBIDDEN.
• Posts, scheduled jobs and requests of other profiles answer 404, as if they didn't exist.
• GET /v1/profiles lists only the key's profiles.
• The workspace-wide webhook needs a key without a profile limit; per-profile webhooks work.

Test keys

A test key (rs_test_…) runs every check a live key does, and its posts show as done, but nothing reaches the networks and nothing counts against your plan's monthly uploads. A workspace can send up to 500 test posts a day; past that the answer is 429 with error_code: TEST_LIMIT.

Only posting is simulated. Other calls made with a test key act on your real workspace: creating or deleting profiles, connecting accounts, the media library, and AI captions (which use your AI credits). See Test mode.

Expiry and revoking

A key with an expiry date stops working at that moment and answers 401 API key expired. The dashboard shows which keys expire within 14 days.

Revoking a key in the dashboard takes effect on the next request. To rotate a key without downtime:

1. Create the new key.
2. Deploy it everywhere the old one is used.
3. Revoke the old key.

When authentication fails

Error bodies look like this:

{ "success": false, "message": "This API key does not have the \"webhooks\" scope", "error_code": "INSUFFICIENT_SCOPE" }

Every answer to a valid key also carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. See Rate limits.

Keep keys safe

• Keep keys on your server. Never put one in a web page, a mobile app or a public repository.
• Store keys in environment variables or a secrets manager, not in code.
• Give each integration its own key with only the scopes it needs, so you can revoke one without breaking the others.
• Limit keys to the profiles they serve, and set an expiry on keys for short-lived work.
• Use a test key while you build, and a live key only in production.
• If a key may have leaked, revoke it at once and create a new one.

AI agents

The MCP server accepts the same API key. Claude and ChatGPT can also sign in to it with OAuth instead of a key.