Skip to content
Jetrepo
Esc
↑↓navigate↵open⌘Jpreview
On this page

Endpoints and auth

Choose a delivery endpoint and the correct delivery, preview, or agent credential.

Delivery endpoints are read-only and use either a Backend- and Environment-scoped delivery key or a Preview Bearer. Management MCP uses a separate agent or delegated credential.

Endpoint map

Method and path Credential Purpose
GET /rest/{typeKey} Delivery key or Preview Bearer List Content or Assets
GET /rest/{typeKey}/{id} Delivery key or Preview Bearer Read one record
GET /rest/taxonomy/{vocabularyKey} Delivery key or Preview Bearer List Terms
GET /rest/taxonomy/{vocabularyKey}/{id} Delivery key or Preview Bearer Read one Term
GET /openapi.json Delivery key or Preview Bearer Generated OpenAPI 3.1
GET /docs Delivery key or Preview Bearer REST API browser
POST /preview/sessions/exchange One-time bootstrap code Create a Preview Bearer
POST /context/mcp Delivery key or Preview Bearer Read-only agent retrieval
POST /agent/mcp Agent key, Agent Auth, or OAuth Management MCP

Delivery keys

A key has either delivery.readPublished or delivery.readPreview. Each permission requires matching Backend and Environment scopes; Data Type, locale, and Vocabulary selectors do not apply to delivery keys.

Send the key as x-api-key and select the stable Backend with x-backend-id. Select delivery state with either x-environment-alias or x-environment-id, never both. Without an Environment selector, Jetrepo resolves the protected production Alias. Without x-backend-id, Jetrepo can infer a Backend only when the key’s Backend selector is SELECTED with exactly one ID.

Published REST responses identify the resolved X-JetRepo-Backend-Id, X-JetRepo-Environment-Id, X-JetRepo-Manifest-Id, and X-JetRepo-Manifest-Hash. These are immutable provenance and operational-attribution headers, not additional authorization material.

curl https://delivery.example.com/rest/article \
  -H 'x-api-key: YOUR_DELIVERY_KEY' \
  -H 'x-backend-id: BACKEND_ID' \
  -H 'x-environment-alias: production'

Use x-backend-id only when the key does not select exactly one Backend. Prefer an Alias for long-lived integrations; an Environment ID is useful for explicitly pinned non-production delivery.

Delivery-key cache and revocation

Delivery caches key verification and Backend/Environment resolution for DELIVERY_AUTH_CACHE_TTL milliseconds: 5000 by default, or 0 to check the database on every key-authenticated request. A revoked, disabled, expired, or re-scoped key can remain usable until that cache entry expires. Cached failures can also delay a newly permitted request. This boundary applies to REST and key-authenticated Context MCP. Preview Bearers use their separate live session checks; Management OAuth and Agent Auth use their own next-request revalidation.

Preview Bearers

Exchange a single-use code without an authentication header:

curl https://delivery.example.com/preview/sessions/exchange \
  -H 'content-type: application/json' \
  --data '{"bootstrapCode":"jp_boot_REPLACE_ME"}'

Then keep the returned token server-side and send it to REST:

curl https://delivery.example.com/rest/article \
  -H 'authorization: Bearer jp_prev_REPLACE_ME'

A Preview session captures and rechecks the human actor’s live content, Release, locale, and Vocabulary authorization. Never send x-api-key and a Preview Bearer together.

Error boundaries

  • Missing or invalid delivery key: 401.
  • No resolvable Backend, Alias, or Environment—or a selector outside the key scope: 403.
  • Both Environment selector headers: rejected as outside the resolvable key scope with 403.
  • Delivery key plus Preview Bearer: 400.
  • The Delivery API does not install browser CORS middleware; call it from server-side code.
  • Agent keys are accepted only by Management MCP.

Was this page helpful?