Production integration

Keep organization keys on the server

Use a Bearer token:

Authorization: Bearer rbk_your_key_here

Scope	Access
tasks:read	Read Agents, Conversations, Responses, Messages, and streams.
tasks:write	Create, update, delete, submit, interrupt, and answer.

Creating a Response requires both scopes.

An organization key has no end-user identity. Authenticate users in your application and check their access to each Conversation before calling Rebyte. Never send the key to a browser or mobile client.

The API_KEY, api-key, and x-api-key headers are also accepted. If a Bearer token and API-key header are both present, their values must match.

Use idempotency keys for writes

Operation	Idempotency-Key
Create Agent	Optional
Create Response	Optional
Create Session	Optional
Submit Session Message	Required

The key must be 1–255 visible ASCII characters. Retrying the same key and body returns the same resource. Reusing the key with a different body returns 409 idempotency_key_conflict.

Use a stable application request ID. On a network failure, retry the same body with the same key; do not create a new key for the same logical write.

Reconcile after disconnects

Live streams are delivery channels, not the source of final state.

• Retrieve a Response with GET /v1/responses/{response_id}.
• Retrieve a Message with GET /v1/sessions/{session_id}/messages/{message_id}.
• Treat async Message 202 as accepted, not completed.
• After interrupting, read the Message until it reaches a terminal status.

A synchronous Response can return 504 response_timeout after five minutes. The request timeout does not prove that stored execution was canceled.

Handle errors by status

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": []
  }
}

Status	Action
400	Fix the request. Unknown fields are rejected.
401	Replace the missing, invalid, expired, or conflicting key.
402	Choose an available model or change the organization plan.
403	Add the required key scope.
404	Verify the resource ID and organization.
409	Resolve current state or an idempotency-body conflict.
504	Reconcile the durable Response or Message before retrying.

Do not blindly retry validation, authorization, ownership, or state-conflict errors.

Proxy browser streams without buffering

The browser-facing endpoint in your application should:

1. authenticate the application user;
2. authorize the Conversation;
3. add the Rebyte Agent ID and organization key;
4. forward the upstream status, SSE headers, and body;
5. abort upstream work when appropriate and expose a separate interrupt route.

See the TypeScript SDK browser boundary for the client payload.