Authentication

One key, one environment, one explicit entitlement.

CorpusMesh issues private-beta credentials manually. Keys stay on your server and identify an API client; entitlements determine which immutable knowledge-base versions and profiles that client can retrieve.

Header
Authorization: Bearer
Scope
retrieval:read
Boundary
client · environment · entitlement
Issuance
Manual review
Developer docsAuthentication

Request authentication

Keep the credential behind your application boundary.#

Load the issued key from a server secret store and send it in the authorization header. Do not put it in a browser bundle, mobile application, URL, analytics property, log, or repository.

  • Server-side only

    Read the key at runtime from a secret manager or protected environment variable.

  • Never identify users

    The API key identifies your service client. Do not create one key per end user or send personal data in the key label.

  • Use retry identity separately

    Idempotency-Key identifies one retried request. It is not an authentication credential.

Request headersExample
Authorization: Bearer cm_test_••••••••
Content-Type: application/json
Idempotency-Key: request-article-6-001

Access resolution

A valid key alone never grants corpus access.#

The server verifies the keyed digest, environment, client status, organization status, scope, active entitlement, authorized corpus version, and selected retrieval profile.

A missing scope, revoked client, inactive organization, wrong environment, or unavailable entitlement stops the request before paid retrieval work.

Authentication and entitlement resolutionfails closed
  1. Credentialkey digest · client · environment
  2. Authorizationorganization · entitlement · version · profile
  3. Outcomeretrieve · fail closed · audit

Environment separation

Test and live credentials do not cross.#

The environment is part of the client boundary, not a naming convention. A test key cannot authenticate against live access, and a live key cannot be used for test fixtures.

cm_test_…

Integration and acceptance.

Use test access for contract integration, bounded fixtures, error handling, and rollout verification before promotion.

cm_live_…

Approved production traffic.

Live credentials are issued separately only after the activation gate, entitlement, limits, and rollback path are approved.

Credential lifecycle

Rotation changes the secret, not the accountability trail.#

CorpusMesh records issuance, activation, rotation, revocation, and entitlement changes as auditable operations. A revoked key fails immediately.

Issue
A scoped client and environment receive a credential through a controlled handoff.
Rotate
A replacement key is activated and the previous secret is revoked without widening the entitlement.
Revoke
The credential stops authenticating. Historical usage and audit records remain attributable to the client.

Access boundary

Start with the workflow, then issue the minimum credential.

Private-beta access is reviewed against the requested corpus, environment, filters, and expected request volume.