Skip to content

Product documentation

Publish Terms of Use and Privacy Policy for an application

Version, publish, and activate an application's Terms of Use and Privacy Policy from the customer plane — a tenant admin API that proxies to identity-service's per-client legal-document store, gated on tenant:compliance.* and scoped to clients the tenant owns.

Publish legal documents for an application

Each of your applications (relying parties) can carry versioned Terms of Use and Privacy Policy documents. Publishing a version activates it immediately and forces your end users to re-accept it at the next login. This surface is part of the customer plane — a tenant admin administers it from the console, no operator involvement.

The documents themselves live in identity-service (the same store its login-time consent gate reads). product-api is a read-through proxy: it verifies the application belongs to your tenant, then forwards to identity over an in-cluster server-to-server channel. No document data is duplicated into the customer plane.

For end users (tenant admins)

  1. Open the application in the console and go to its Legal documents section.
  2. Publish a new Terms of Use or Privacy Policy version — supply a version label, a title, and the URL where the document text is hosted.
  3. The new version is activated automatically; the previous active version is deactivated. Your end users are prompted to accept the new version on their next sign-in.
  4. You can list historical versions, re-activate an older one, and delete a version that has not yet been accepted by anyone.

Endpoint reference

All paths are scoped to a single application by its clientId. {docType} is either terms-of-use or privacy-policy.

MethodPathDescriptionScope
POST/api/v1/applications/{clientId}/{docType}Publish + activate a new versiontenant:compliance.write
GET/api/v1/applications/{clientId}/{docType}List all versions (newest first)tenant:compliance.read
GET/api/v1/applications/{clientId}/{docType}/{id}A single version + acceptance counttenant:compliance.read
POST/api/v1/applications/{clientId}/{docType}/{id}/activateActivate a specific versiontenant:compliance.write
DELETE/api/v1/applications/{clientId}/{docType}/{id}Soft-delete an unaccepted versiontenant:compliance.write

The publish body is:

{
  "version": "2.0",
  "title": "Terms of Use",
  "contentUrl": "https://legal.example.com/tou/2.0"
}

Troubleshooting

  • 404 not_found — the clientId is not one of your tenant's applications (in the environment your token resolves to). Cross-tenant access always returns 404, never 403, so there is no way to probe for another tenant's client ids.
  • 403 — your token is missing the required tenant:compliance.read / tenant:compliance.write scope.
  • 409 document_accepted — you tried to delete a version that end users have already accepted. Acceptance records are a GDPR Art. 7 audit trail and are never destroyed; publish a superseding version instead.
  • 502 upstream_identity_error — identity-service was unreachable; retry.
  • 503 facade_not_configured — the deployment has no legal-document facade configured (self-managed deployments must mount the projected service-account token).

Security notes

  • The tenant-to-client binding is enforced in product-api's tenant_application mapping on every request — a client your tenant does not own is invisible (404).
  • product-api reaches identity-service over the in-cluster projected-ServiceAccount IdP facade (audience identity-tenant-facade); no shared secret, and the target host is fixed and operator-configured (never derived from request input).
  • Acceptance evidence is retained even after a document version is deleted, to satisfy GDPR Art. 7 consent record-keeping.