Authentication

Every request to the Seller API must include a valid API key in the Authorization header using the Bearer scheme.

Authorization: Bearer ssk_live_a8KfJN2mP9xQR4tV...

Requests without a valid key, or whose key has been revoked, return 401 unauthorized. Requests from a server that is not on the Max plan return 403 plan_required.

Key format

API keys look like:

ssk_live_<42 url-safe characters>

• ssk — Subscord secret key
• live — environment indicator (reserved for a future test mode)
• The remaining string is 32 random bytes encoded as base64url

The ssk_live_ prefix lets you identify Subscord secrets at a glance in logs, configuration files, and secret scanners. Treat keys like passwords — never commit them, never expose them client-side, never log them.

Creating an API key

1. Open your Subscord Dashboard.
2. Go to Settings → API Keys.
3. Click Create API Key and give it a memorable name (e.g. Production, Staging, Internal Tool).
4. Copy the key from the dialog. You will only see the full key once — store it in a secrets manager immediately.

You can have up to 5 active keys per server. To create more, revoke an existing key first.

Rolling a key

Rolling a key generates a brand new key with the same name and immediately revokes the old one. Use this whenever you suspect a key may have been exposed, or as part of a regular rotation schedule.

1. Settings → API Keys.
2. Click Roll next to the key you want to rotate.
3. Confirm. The new key is shown once — copy it and update your integration.

The old key stops working immediately. Plan for a brief deployment window when rolling production keys.

Revoking a key

Revoking permanently disables a key. Revoked keys remain visible in the dashboard so you can see when and why they were retired.

1. Settings → API Keys.
2. Click Revoke next to the key.
3. Confirm.

Revoked keys cannot be reactivated — create a new key if you need access again.

Scope

Each API key is scoped to a single Discord server (guild). There is no way to create a key that operates across servers. If you manage multiple servers and need API access to each, create one key per server.

The key implicitly carries:

• Server identity — every request operates on the server the key was issued for.
• Plan check — keys belonging to a server that is no longer on the Max plan are rejected with 403 plan_required.

There is no concept of scoped permissions (read-only vs. write) at this time.

Handling key compromise

If a key is exposed (committed to a repo, leaked in logs, shared by mistake), revoke it immediately in the dashboard. Then:

1. Audit recent API activity (the dashboard shows Last used per key).
2. Create a new key.
3. Update your integration.

Subscord will not be able to recover or "show" a key after it has been created — you must roll or revoke it.

Common authentication errors

See Errors for the full error response shape.