Publish a legal document

POST /v1/legal-documents · permission legal-documents:write

Publishes a version of a legal document. KeenAuth fetches url once through its egress proxy and stores the SHA-256 hash of the body as content_sha256: HTTPS only, private and platform addresses blocked, at most 5 MiB, 10 seconds; a non-200 response or an empty body counts as unreachable and nothing is stored. url, version, locale and the hash never change after publishing. effective_at defaults to now and cannot be in the past.

Request

JSON body (unknown fields are rejected with 400 unknown_field):

Field Type Required Description
Idempotency-Key header no Optional key (16-64 characters) that makes a retried request safe.
kind string yes terms, privacy_notice or custom.
version string yes Your version label, 1-64 characters.
locale string yes BCP 47 language tag; must be enabled in the environment.
url string yes HTTPS page you host, at most 2048 bytes.
application_id string | null no Application the document applies to (app_…); omitted or null means every application of the environment.
effective_at string (date-time) no When the document takes effect; defaults to now, cannot be in the past.
requires_reacceptance boolean no When true, users see the re-acceptance screen at their next interactive sign-in after effective_at. Default false.

Response

201 Created with the document.

{
  "id": "ldoc_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "application_id": null,
  "kind": "terms",
  "version": "2026-10",
  "locale": "en",
  "url": "https://example.com/legal/terms-2026-10",
  "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "effective_at": "2026-11-01T00:00:00Z",
  "requires_reacceptance": true,
  "created_at": "2026-10-05T09:30:00.123456Z",
  "updated_at": "2026-10-05T09:30:00.123456Z"
}

Errors

HTTP code When
400 unknown_field The body contains an unknown field.
409 conflict A document with the same application, kind, version and locale already exists.
415 unsupported_media_type The content type is not application/json.
422 legal_document_unreachable The URL could not be fetched or hashed through the egress proxy; nothing was stored.
422 validation_failed A field is invalid (for example url not HTTPS, unknown locale, effective_at in the past, or application_id not in the environment: unknown_application).
401 unauthenticated The credential is missing, invalid or revoked.
403 insufficient_permissions The credential lacks the required permission.
429 rate_limited The rate limit was exceeded; retry after the Retry-After period.
503 service_unavailable Document fetching is not configured in this deployment, or a dependency is temporarily unavailable.

Example

curl -X POST https://api.eu.keenauth.com/v1/legal-documents \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind":"terms","version":"2026-10","locale":"en","url":"https://example.com/legal/terms-2026-10","effective_at":"2026-11-01T00:00:00Z","requires_reacceptance":true}'