Developers
Authentication, scopes, brands, and IDs
Use API keys or MCP OAuth with the right scopes. Understand brand IDs, brand UUIDs, account access, and credential revocation.
Updated
Authenticate every request
Send Authorization: Bearer followed by your krv_ API key. X-API-Key is also accepted. MCP OAuth access tokens use the krvo_ prefix and work through the same authentication path. Choose one header; do not send conflicting credentials.
Authorization: Bearer <your-api-key>Keys inherit the owner's account access. Revoked keys and inactive or deleted accounts cannot authenticate. The account's current plan is checked on every request; a previously created key does not preserve an expired entitlement.
Choose the smallest useful set of scopes
| Scope | Allows | Common use |
|---|---|---|
| read | Read posts, assets, brands, analytics, memory, and job status | Reporting or queue review |
| publish | Create and edit posts, approve, schedule, and edit Canvas designs | Draft submission or publishing workflow |
| generate | Repurpose sources, generate a week, update memory, start exports and imports | Content generation and asynchronous work |
| media | Upload/delete assets and create/edit/export drawings | Media library integration |
| engage | Send or dismiss supported replies and engagement actions | User-directed engagement |
A key created without a scopes list defaults to read. The publish scope does not grant engage. A scope is permission to call a tool; it does not bypass a feature preview gate, account connection requirement, storage quota, or plan limit.
Create, rotate, and revoke credentials
| Signed-in session route | Result |
|---|---|
| POST /apikeys | Create with name and optional scopes; returns the key once (201) |
| GET /apikeys | List key metadata and prefixes |
| DELETE /apikeys/{key_id} | Revoke a key (204) |
These routes require a dashboard session token, not an API key. Creating a key also requires a verified account. You can have up to 10 active keys. To rotate, create a replacement, update your integration's stored secret, verify GET /v1/me, then revoke the old key. API keys cannot create other keys.
Connect an OAuth-capable MCP client
Add https://api.krevaya.com/mcp as a Streamable HTTP server in your client and use its sign-in flow. Krevaya shows the app and requested scopes for consent. The connection appears as a connected-app key in Settings; revoking that row cuts off subsequent requests.
| OAuth endpoint | Purpose |
|---|---|
| GET /.well-known/oauth-protected-resource/mcp | Protected-resource discovery |
| GET /.well-known/oauth-authorization-server | Authorization-server discovery |
| POST /oauth/register | Dynamic client registration |
| GET /oauth/authorize | Start authorization and consent |
| POST /oauth/token | Exchange a code or refresh token |
| POST /oauth/revoke | Revoke a token |
Authorization codes require PKCE S256, are single use, and require an exactly registered redirect URI. Access tokens last seven days. Refresh tokens last 90 days and rotate when used; save the replacement refresh token atomically. An OAuth connection has the same scopes and plan rules as a pasted key.
Resolve the brand before writing
Use MCP list_brands to obtain the numeric ID string used by brand_id on REST and most MCP tools. Omitting brand_id follows the dashboard's active brand; some read tools can follow its All-brands view. A workflow that runs while someone switches brands should pass an explicit brand ID wherever supported.
A brand UUID is a different identifier. MCP create_design requires brand_uuid. Obtain the UUID from an existing post's brand_uuid field, or the signed-in brand API. list_brands currently returns the numeric id but not the UUID. Never substitute the numeric ID for brand_uuid or infer another user's brand from a URL.
Some operations, including /v1/generate and MCP draft_week, have no brand_id argument. They use the current brand context. Select and verify that brand before starting them; do not add an undocumented request field.
Preserve identifiers exactly
| Identifier | Representation | Where it is used |
|---|---|---|
| Post, asset, drawing, job, brand ID | Decimal string on the wire | REST parameters and MCP arguments |
| Post or brand UUID | UUID string | Shareable routes and explicit brand_uuid fields |
| layout_version or memory version | Integer counter | Optimistic concurrency checks |
JSON input accepts decimal ID strings even when the server's model describes an integer. Keep IDs as strings in JavaScript and GraphQL ID values. Version counters, dimensions, durations, counts, and offsets are ordinary numbers.
Frequently asked questions
Why does a valid key return 403?
The key can be missing the required scope, or the account can lack the current plan or feature entitlement. Read the response detail before changing credentials.
Is brand_id the same as brand_uuid?
No. brand_id is a decimal row ID sent as a string. brand_uuid is a UUID. create_design requires the UUID; most REST brand filters use the numeric ID string.