Authentication
Every request uses an API key in a Bearer header. Learn how keys work, what scopes they carry, and the plan they require.
Every /v1/* endpoint is authenticated with an API key sent as a Bearer token:
Authorization: Bearer sk_live_abc123def456...API keys
Keys are created in the Someone app settings page. A key is shown once at creation — only a SHA-256 hash is stored, so copy it immediately and keep it secret.
| Property | Value |
|---|---|
| Format | sk_live_ + 64 hex characters |
| Max active keys | 10 per user |
| Storage | Only the hash is kept; the plaintext is never recoverable |
Each key also generates a webhook_secret (format whsec_...) reserved for customer webhook delivery once that feature is certified. Creating the secret does not enable webhooks today.
Scopes
Keys carry least-privilege scopes. Write operations require the matching scope, and scope is checked before any resource or pricing read:
| Scope | Grants |
|---|---|
characters:write |
Create, regenerate, revert characters |
images:generate |
Create image generations |
videos:generate |
Create video and lipsync generations |
speech:generate |
Create audio (text-to-speech) |
voices:write |
Clone or design voices |
A request whose key lacks the required scope is rejected before it touches your resources.
Managing keys (in the web app)
Key lifecycle is handled by the Someone app, not the public API:
| Method | Path | Description |
|---|---|---|
POST |
/api/keys |
Create a new key (returns the plaintext + webhook_secret once) |
GET |
/api/keys |
List keys (prefix, name, last_used_at, created_at) |
DELETE |
/api/keys/:id |
Revoke a key (soft delete) |
Authentication errors
| Code | Status | Meaning |
|---|---|---|
missing_api_key |
401 | No Authorization header |
invalid_api_key |
401 | Key not found or revoked |
expired_api_key |
401 | Key passed its expiration date |
plan_required |
403 | The key owner has no active Creator or Studio plan |