Authentication

All API requests require authentication via a Bearer token in the Authorization header. The one exception is the thumbnail of a public scene (GET /v1/scenes/{id}/thumbnail), which needs no key.

API keys

API keys use the s3d_ prefix and are passed as Bearer tokens:

curl https://api.splat-3d.com/v1/scenes \
  -H "Authorization: Bearer s3d_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Creating a key

Sign in to the Splat3D dashboard
Go to Settings > API Keys
Click Create Key and give it a name
Copy the key immediately — it’s only shown once

Your API key is shown exactly once when created. Store it securely. If you lose it, revoke the old key and create a new one.

Scopes

A key carries the scopes picked when it was created, All by default. The API checks them on every request (requireScope in api/src/middleware/scope.ts):

Pick	Scope	Allows
Read	`read:scenes`	Listing, reading and downloading your scenes
Write	`write:scenes`	What Read allows, plus creating, editing, deleting, processing, retraining and cancelling scenes. Processing and retraining spend credits
All	`*`	Every endpoint

GET /v1/usage takes any key. A key without the scope an endpoint needs gets 403 insufficient_scope, before anything is read, changed or charged:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key lacks the write:scenes scope. Use a key created with Write or All access."
  },
  "meta": { "request_id": "..." }
}

Key format

Property	Value
Prefix	`s3d_`
Length	36 characters total (`s3d_` + 32 hex chars)
Entropy	128 bits (cryptographically random)
Storage	SHA-256 hashed server-side

The web dashboard generates keys as s3d_<32 hex chars> (POST in web/src/app/api/internal/keys/route.ts) and stores only the SHA-256 hash. The API authenticator validates the s3d_ prefix and looks up the SHA-256 hash; there is no length or entropy check at the edge beyond the prefix (requireApiKeyAuth in api/src/middleware/auth.ts).

Key management

API keys are managed exclusively from the web dashboard at https://splat-3d.com/dashboard/settings. There is no public API for listing, creating, or revoking keys — this is by design to keep the auth perimeter simple. You can have up to 5 active API keys per account (MAX_ACTIVE_KEYS in web/src/app/api/internal/keys/route.ts).

Rate limits

Limit	Value	Enforced by
Requests per minute	300 on every plan, per account (all its keys together), or per client IP for a request with no key or a key that matches no account	`REQUESTS_PER_MINUTE` in `api/src/middleware/rate-limit.ts`
Create, `/process` and `/retrain` requests per minute	30 on every plan, per account, counted in the 300 too	`LAUNCHES_PER_MINUTE` in `api/src/middleware/rate-limit.ts`
Scenes processing at once	2 on every plan, checked when `/process` starts a scene	`maxRunningScenes` in `packages/core/src/plans.ts`
Scene creations per month	10 on Explorer (free) · 100 on Creator (any account that has bought a credit pack)	`api/src/middleware/quota.ts` `PLAN_LIMITS`
Scene processes per month	10 on Explorer (free) · 100 on Creator (any account that has bought a credit pack)	`api/src/middleware/quota.ts` `PLAN_LIMITS`
Max upload size	5 GB on every plan (R2’s single-PUT maximum)	`MAX_UPLOAD_BYTES` in `packages/core/src/uploads.ts`, checked by R2 HEAD at `POST /v1/scenes/{id}/process`

A request over a per-minute limit answers 429 rate_limited with Retry-After: 60. It is refused before it reads or changes any scene, quota or credit balance: nothing is charged and no scene is made. Wait Retry-After seconds, then send the same request again. Polling at the recommended 5 to 10 seconds stays well under the limit: 5 scenes polled every 5 seconds is 60 requests a minute.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit reached: 300 requests a minute. Retry after 60 seconds."
  },
  "meta": { "request_id": "...", "limit": 300 }
}

Every /v1 response carries X-RateLimit-Limit, the requests a minute its route allows: 30 on create, /process and /retrain, 300 on the rest. A 429 rate_limited names the limit that refused it, there and in meta.limit. There is no X-RateLimit-Remaining: the counter behind the limits only says whether a request is over.

The limits are counted per Cloudflare location and approximately: a fast burst can pass one several times over before its first 429, and a refusal can clear in under a minute. Don’t plan against the exact numbers. They stop runaway loops and stolen keys; the monthly quotas and credits below do the metering.

When your scenes processing reach the cap, POST /v1/scenes/{id}/process (and /retrain) returns 429 queue_full with Retry-After: 120. Nothing is charged and the scene stays uploading: call /process again once one finishes. A refused /retrain keeps no new version, unless the response carries no Retry-After: then check GET /v1/scenes before sending it again. Creating and uploading a scene is never refused for this.

{
  "error": {
    "code": "queue_full",
    "message": "You have 2 scenes processing, and your plan allows 2 at once. Try again when one finishes."
  },
  "meta": { "request_id": "...", "limit": 2, "current": 2 }
}

Deleting a scene that is still processing cancels it first, under the cancel refund rules. A create counts against the scene-creation quota only once it makes a scene, so a refused create counts nothing. A retrain whose launch is refused before any charge (for example 402, 413, 422 or 429) keeps no new scene, so it counts nothing. One whose launch is charged and then fails (502) keeps its new scene, which counts. When you hit a monthly quota, the API returns 429 quota_exceeded:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly scene processing limit reached."
  },
  "meta": { "request_id": "...", "period": "2026-05", "limit": 10, "field": "scenes_processed" }
}

Error responses

All authentication errors follow the standard error envelope:

Status	Code	Meaning
`401`	`unauthorized`	Missing or invalid API key
`403`	`forbidden`	Valid key, but you don’t own this resource
`403`	`insufficient_scope`	Valid key, but its scopes don’t cover this endpoint
`429`	`rate_limited` / `queue_full` / `quota_exceeded`	Too many requests this minute, too many scenes processing at once, or a monthly quota used up
`503`	`service_unavailable`	The key couldn’t be checked right now, so this says nothing about it: a valid, unknown or revoked key gets the same answer. Retry after `Retry-After` seconds when the response carries one

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required."
  },
  "meta": {
    "request_id": "abc123"
  }
}

Best practices

Use environment variables for your API keys. Never hardcode them in source code or commit them to version control.

One key per environment — separate keys for development, staging, and production
Rotate regularly — revoke and replace keys periodically
Use descriptive names — name keys after their purpose (e.g., “production-backend”, “ci-pipeline”)
Monitor usage — the dashboard shows the last_used_at timestamp for each key so you can spot unused ones and revoke them

Getting Started

Guides

Authentication

Authentication

API keys

Creating a key

Scopes

Key format

Key management

Rate limits

Error responses

Best practices

​Authentication

​API keys

​Creating a key

​Scopes

​Key format

​Key management

​Rate limits

​Error responses

​Best practices

Authentication

API keys

Creating a key

Scopes

Key format

Key management

Rate limits

Error responses

Best practices