Authentication
How the CentraKit API authenticates browser sessions and bearer tokens, and how clients get tokens through Supabase OAuth 2.1, PKCE and dynamic client registration.
Webhooks
Send signed CentraKit events to your HTTPS endpoints and receive external webhooks that start workflows, including signatures, secret and token rotation, delivery retries, and the REST and MCP operations.
Authentication
How the CentraKit API authenticates browser sessions and bearer tokens, and how clients get tokens through Supabase OAuth 2.1, PKCE and dynamic client registration.
Webhooks
Send signed CentraKit events to your HTTPS endpoints and receive external webhooks that start workflows, including signatures, secret and token rotation, delivery retries, and the REST and MCP operations.
The RFC 9457 problem details format that every CentraKit API and MCP error uses, how codes and statuses are derived, and how to handle APPROVAL_REQUIRED.
Every CentraKit API error is an RFC 9457 problem details document served with Content-Type: application/problem+json and Cache-Control: private, no-store. MCP tool errors carry the same document, so clients can branch on one set of codes.
{
"type": "https://docs.centrakit.com/developers/errors#CUSTOMER_NOT_FOUND",
"title": "Customer not found",
"status": 404,
"detail": "The customer could not be found.",
"code": "CUSTOMER_NOT_FOUND",
"messageKey": "customer.error.notFound"
}| Member | Meaning |
|---|---|
type | URI that identifies the problem. Always https://docs.centrakit.com/developers/errors#<code>. |
title | Short summary derived from the code, such as Customer not found. It is the same for every occurrence. |
status | HTTP status code, repeated in the body. |
detail | Human-readable explanation of this occurrence. Optional, and not stable. |
instance | URI reference for this occurrence. Optional. |
code | Stable machine code. Branch on this, not on detail or title. |
messageKey | Translation key a client can use to show localized copy. |
errors | Optional list of { "detail": "...", "pointer": "..." } validation issues. |
Some problems add extension members next to these, such as approvalId. The standard members always win over an extension with the same name.
Domain services return tagged errors such as CustomerNotFoundError. The API turns the tag into the code by dropping Error and converting to upper snake case, so CustomerNotFoundError becomes CUSTOMER_NOT_FOUND with the message key customer.error.notFound.
Unless a route sets the status explicitly, the status follows from the tag:
| Tag contains | Status | Example code |
|---|---|---|
Validation | 400 | CUSTOMER_VALIDATION |
Unauthenticated | 401 | CRON_UNAUTHENTICATED |
Forbidden or PermissionDenied | 403 | ORGANIZATION_PERMISSION_DENIED |
NotFound or TokenInvalid | 404 | ORGANIZATION_NOT_FOUND |
Conflict, Expired, StateError or ApprovalRequired | 409 | APPROVAL_REQUIRED |
Unavailable | 503 | CRON_UNAVAILABLE |
| Anything else | 500 | CUSTOMER_UNEXPECTED |
Routes set other statuses where a fixed mapping does not fit:
| Code | Status | Where |
|---|---|---|
AUTH_* | varies | Authentication. See Authentication. |
RATE_LIMITED | 429 | Incoming webhooks, with a retry-after header. |
PAYLOAD_TOO_LARGE | 413 | Incoming webhook bodies over 256 KB. |
NOT_FOUND, UNAUTHORIZED, DISABLED, FAILED | 404, 401, 404, 500 | Incoming webhook receiver results. |
API_UPSTREAM | 502 or the upstream status | An MCP tool got a non-problem error from the REST API. |
Pre-boarding links and the portal quote change request also answer 429 when a caller sends too many requests.
The assistant transports under /api/v1/ai/chat use the same problem format with lowercase codes, for example rate_limited (429, with Retry-After), billing_limit_reached, model_unavailable, unsupported_attachment and stale_message_delta (409). These routes serve the SaaS app and are not part of the public API.
POST /api/v1/organizations/{organizationId}/ai/agent-runs/{runId}/approvals/{approvalId} adds continued and decided booleans to its problems, so the client knows whether the run moved on.
An organization can require approval before certain actions run. When a mutation waits on an approval policy, it answers 409 with code APPROVAL_REQUIRED and an approvalId:
{
"type": "https://docs.centrakit.com/developers/errors#APPROVAL_REQUIRED",
"title": "Approval required",
"status": 409,
"detail": "This order needs approval before it can be confirmed.",
"code": "APPROVAL_REQUIRED",
"messageKey": "order.error.approvalRequired",
"approvalId": "0f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b"
}Over REST, the order, shipment and purchase order routes run the policy themselves: creating, confirming and cancelling an order, shipping a shipment, and creating or receiving a purchase order.
Over MCP, every mutation tool that maps to an action in the approval catalog runs the policy before it calls the REST route. Those problems also include:
| Member | Meaning |
|---|---|
requirement | confirm when the user has to confirm it in Notifications, or authorize when someone else has to approve it. |
approverPermission | The permission an approver needs, or null. |
To handle it, tell the user who has to act, wait until the request is decided, and send the same request with the same input again. See Approvals.
Inside the monorepo, @workspace/foundation/api/problem-details reads and validates problem documents:
import { readProblemDetails } from "@workspace/foundation/api/problem-details";
const response = await fetch(url, { headers });
if (!response.ok) {
const problem = await readProblemDetails(response);
if (problem?.code === "APPROVAL_REQUIRED") {
console.info("Waiting for approval", problem.approvalId);
}
}The generated @workspace/api-client SDK returns the problem as result.error. Use getApiProblem(result.error) or getApiErrorMessageKey(result.error) from @workspace/api-client/client to read it. Any other client can parse the JSON body and branch on code.
A failed MCP tool call returns isError: true. Its structuredContent is the problem document, and its text content is the same document as JSON. For APPROVAL_REQUIRED, the detail already tells the agent to call the tool again with the same input once the request is approved.
The CLI prints the problem detail (or title) followed by the code, for example The organization could not be found. (ORGANIZATION_NOT_FOUND), and exits with status 1.
Last updated on
Authentication
How the CentraKit API authenticates browser sessions and bearer tokens, and how clients get tokens through Supabase OAuth 2.1, PKCE and dynamic client registration.
Webhooks
Send signed CentraKit events to your HTTPS endpoints and receive external webhooks that start workflows, including signatures, secret and token rotation, delivery retries, and the REST and MCP operations.