---
title: "API authorization and rules"
description: "Keys, capabilities, errors, pagination and idempotency."
group: "Technical documentation"
order: 20
---

## Deployment addresses

- Documentation: https://ctx4.me/docs.md
- Agent index: https://ctx4.me/docs/agent-index.json
- Console and connections: https://console.ctx4.me/integrations
- MCP: https://ctx4.me/mcp
- HTTP API: https://ctx4.me/v1
- Composio base URL: https://ctx4.me/compat/context4/v1
- OpenAPI: https://ctx4.me/docs/openapi.json
- HTTP/MCP inventory: https://ctx4.me/docs/api-index.json
- Composio routes: https://ctx4.me/docs/compat-routes.json
- Connectors: https://ctx4.me/docs/connectors.json


# API authorization and rules

## Address and authorization

This deployment's API address: `https://ctx4.me/v1`. [Console and connections](https://console.ctx4.me/integrations). The `CONTEXT4_API_KEY` variable holds your secret server-environment key; the documentation does not substitute it.

```bash
curl "https://ctx4.me/v1/identity" \
  -H "Authorization: Bearer $CONTEXT4_API_KEY"
```

A key is issued in the console and displayed once. Its format is `ctx4_<env>_<secret>`. A key is scoped to an organization, workspace and set of capabilities. A resource belonging to another tenant returns `404 not_found`. The required capability for each method appears in the [reference](https://ctx4.me/docs/api-reference.md).

| Capability | Purpose |
| --- | --- |
| `tools:read` | Tools and HTTP method catalog |
| `executions:read`, `executions:write` | Read and create executions; proxy also requires write |
| `connections:read`, `connections:write` | Connections, auth configs and sources |
| `connections:manage` | Additional permission to manage other users' connections within a tenant; requires connections:write |
| `tool-sessions:read`, `tool-sessions:write` | Tool sessions |
| `syncs:read`, `syncs:write` | Syncs and exports |
| `events:read`, `events:write` | Events and subscriptions |

A missing capability produces `403 capability_missing`. An ordinary key does not gain permission to change another user's connection merely by having `connections:write`. MCP OAuth does not delegate `connections:manage`.

The interface is intended for server use. CORS is not enabled for `/v1`, `/mcp` or compat. Do not put a bearer key in browser code, a URL or a public repository.

## Request bodies and identifiers

Send JSON with `Content-Type: application/json`. The input body limit is 65,536 bytes. Headers and the request line are bounded by the listener; a long vendor URL may be rejected before routing.

`X-Request-Id` is optional: it accepts 1–128 characters matching `[A-Za-z0-9][A-Za-z0-9._:-]{0,127}`. Without it, the server generates a UUID. An invalid value is rejected with `422`; the response includes a new safe request ID. Store `X-Request-Id` and the execution ID for diagnosis.

## Idempotency and retries

Send `Idempotency-Key` when declared in the method's parameters. Its value is 8–128 characters from `[A-Za-z0-9._:-]`. Repeating the same request with the same key returns the original result; a changed body with the previous key produces `409 idempotency_conflict`. Choose a new key for a new intentional operation.

`202` when creating an execution means acceptance or a recorded refusal, not a successful provider change. Read `status`, `denial_code` and the address in `Location`, then poll the execution. Do not automatically repeat a write after a timeout: it may have been applied.

The current `idempotency_conflict` does not distinguish an in-progress request from a mismatched body; it does not promise `Retry-After`. Check the original request and operation state. Mirror API and raw proxy are not idempotent: each call may send a new request to the provider.

## Pagination

Lists use opaque `cursor` and `next_cursor`. Pass the returned cursor unchanged until `null`; do not construct it from an ID. The general `limit` is 1–100, default 20; the reference lists each method's exact parameters and constraints. A cursor is limited to 400 characters. Keep filters unchanged between pages.

Vendor pagination is a separate provider contract: see `paging` in the endpoint descriptor. A Context4 cursor does not imply automatic retrieval of all upstream pages.

## Errors and limits

Platform errors return `application/problem+json` with `type`, `code`, `title`, `status`, `request_id`. Exact enums and fields: [Problem](https://ctx4.me/docs/api-schemas-1.md#problem). Internal causes and credentials are not exposed to the client.

| HTTP | Client action |
| --- | --- |
| 400 | Correct parameters or body; check the schema |
| 401 | Check the key, expiry and revocation |
| 403 | Check capabilities, ownership, policy and session restrictions |
| 404 | Check the ID and access scope |
| 409 | Check version, account or idempotency key conflicts |
| 429 | Respect `Retry-After` if returned |
| 500 | Save the request ID for support |
| 503 | Check service availability; a write retry requires checking its outcome |

`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` describe the API key's minute window; reset is the number of seconds until reset. If Redis is unavailable, writes fail closed with `503`; reads may continue without rate-limit headers. Execution quota and HTTP request rate limits are separate checks.