> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Connect JSON and customer authentication

> **Availability:** This page describes the committed v1 contract; the production endpoint is not necessarily callable.

Connect RPCs use `https://automcp.api.delino.io` and standard Connect JSON. Keep backend keys in a trusted customer server; they are app-bound, scoped, opaque credentials and never browser credentials.

```http
Authorization: Bearer $AUTOMCP_BACKEND_KEY
Content-Type: application/json
Connect-Protocol-Version: 1
```

The customer backend creates or updates an app-scoped customer-user grant, including the opaque external user ID, allowed tools/scopes, exact origins, and optional expiry. It then issues a short-lived browser token. A browser receives only that token, which can narrow the live grant and is checked again when a Run executes.

Workspace requests use canonical lowercase UUID v7 identifiers, mutation request IDs are payload-bound and idempotent, mutable resources require their expected resource version, and list cursors are opaque. Authentication and authorization are separate: app, user, workspace, scope, quota, lifecycle, and spend checks are enforced independently.

Conversation text, memory, tool arguments/results, and encrypted payloads are visible only to the bound customer user or a backend key with explicit user-data scope. Console members, administrators, operators, models, and browsers cannot use another user’s payload or Secret.

## Errors and retries

Connect errors use the standard JSON error envelope. The top-level `code` is
the Connect status code and `message` is a human-readable summary. Typed
`automcp.v1.ErrorDetail` values are carried in `details` as base64-encoded
protobuf messages:

```json
{
  "code": "resource_exhausted",
  "message": "workspace quota exhausted",
  "details": [
    {
      "type": "automcp.v1.ErrorDetail",
      "value": "<base64 protobuf ErrorDetail>"
    }
  ]
}
```

Decode the `value` using the published AutoMCP descriptor or `common.proto`.
The decoded detail includes the failure `reason`, the original `requestId`, a
support-facing `correlationId`, optional `retryAfterSeconds`,
`retryGuidance`, and field-specific violations. Record the request and
correlation IDs when reporting a failure; neither ID is a replacement for the
other, and clients must not depend on an optional human-readable debug object.

Retry only when `retryGuidance` permits it:

- `RETRY_GUIDANCE_AFTER_DELAY`: wait at least `retryAfterSeconds` when it is
  present, then retry the same idempotent request with the same request ID.
- `RETRY_GUIDANCE_AFTER_DEPENDENCY_RECOVERY`: retry after the unavailable
  dependency is healthy again.
- `RETRY_GUIDANCE_AFTER_REAUTHENTICATION`: obtain a fresh credential and
  retry only if the request remains authorized.
- `RETRY_GUIDANCE_AFTER_STATE_CHANGE`: refresh the resource or grant, update
  the request (for example, its expected resource version), and retry only
  after the required state change.
- `RETRY_GUIDANCE_DO_NOT_RETRY`: change the request or stop; do not repeat it.

Quota, rate-limit, concurrency, and dependency failures may be temporary.
Authentication and authorization failures, malformed input, idempotency
conflicts, resource-version conflicts, stopped resources, approval failures,
and unknown outcomes require the corresponding state or recovery action and
must not be blindly retried. A request that may have caused an external effect
must be reconciled when the reason is `ERROR_REASON_OUTCOME_UNKNOWN`.