Authentication

How callers authenticate to the Lattix Platform API using OAuth 2.0 client credentials, OIDC issuer metadata, sender-constrained bearer tokens, tenant binding, scopes, and mTLS proof-of-possession.

Public integrations on https://api.lattix.io use a single steady-state model: obtain an access token from the published OAuth/OIDC issuer, then present that token as a bearer token on /v1/sdk/* routes. When the published proof-of-possession mode is mtls, that bearer token is sender-constrained: the caller also presents a client certificate at the trusted edge, and the token must be bound to that certificate. The Platform API does not expose a public credential-to-token exchange route.

Public flow

Provision a tenant-scoped confidential client in the shared platform issuer.
Request an access token for the api://lattix-platform-api audience.
When proof_of_possession=mtls, present the matching client certificate at the public TLS edge.
Present Authorization: Bearer <access_token> on /v1/sdk/* calls.
Read GET /v1/sdk/capabilities or GET /v1/sdk/bootstrap to confirm the active auth contract and required scopes.

The public issuer published today is https://auth.lattix.io/realms/platform. The current proof-of-possession target is mtls.

Auth mode and configuration

Every authenticated discovery response includes auth_mode and auth_configuration.

{
  "auth_mode": "bearer_token",
  "auth_configuration": {
    "mode": "oauth_client_credentials",
    "proof_of_possession": "mtls",
    "oidc_issuer": "https://auth.lattix.io/realms/platform",
    "oidc_audience": "api://lattix-platform-api",
    "oidc_issuer_ready": true,
    "mtls_ready": true
  }
}

Interpretation:

Field	Meaning
`auth_mode`	`bearer_token` is the expected public value on `api.lattix.io`. Other values indicate private deployment modes, not the public integration contract.
`auth_configuration.mode`	`oauth_client_credentials` means callers obtain tokens from the issuer and then call the API with bearer auth.
`auth_configuration.proof_of_possession`	`mtls` means the public path expects sender-constrained, certificate-bound tokens rather than replayable plain bearers.
`auth_configuration.oidc_issuer`	The issuer to use when minting tokens for the public API.
`auth_configuration.oidc_audience`	The audience the access token must carry.
`auth_configuration.oidc_issuer_ready`	The API verifier is configured to validate the published issuer/audience pair.
`auth_configuration.mtls_ready`	The deployment has published the mTLS proof-of-possession path as ready.

The API never accepts client_secret values on /v1/sdk/* routes. Client secrets are exchanged with the issuer, not with lattix-platform-api.

Bearer token transport

Bearer auth uses the standard header:

Authorization: Bearer <access_token>

The platform derives tenant, principal, subject, and scopes from the access token. Callers should not try to re-assert tenant identity in user-controlled headers on the public path.

On the public mtls path, the token is expected to carry cnf.x5t#S256 for the client certificate presented at ingress. External callers do not send x-lattix-mtls-client-certificate or any other PoP header themselves; the trusted ingress tier validates the client certificate and forwards the bound certificate identity to the API.

If a tenant header is forwarded alongside a bearer token, it must match the tenant claim in the token. Mismatches are rejected.

Scopes

The API uses scope-based authorization. Each route family publishes its required scopes through GET /v1/sdk/capabilities:

{
  "auth_mode": "bearer_token",
  "default_required_scopes": ["platform-api.access"],
  "routes": [
    {
      "route": "/v1/sdk/policy-resolve",
      "domain": "protection",
      "configured": true,
      "required_scopes": ["policy.read"]
    }
  ]
}

The exact scope set is deployment-dependent. Callers should read capabilities at startup, cache the result, and request only the scopes their workload needs.

A 403 response means the caller is authenticated but missing one or more required scopes for the route being called.

Caller identity on every response

Every authenticated /v1/sdk/* response includes the resolved caller under caller:

{
  "service": "lattix-platform-api",
  "status": "ready",
  "caller": {
    "tenant_id": "...",
    "principal_id": "...",
    "subject": "...",
    "auth_source": "bearer_token",
    "scopes": ["platform-api.access", "policy.read"]
  }
}

On the public edge, auth_source is typically bearer_token. Other values represent private or non-public deployment modes.

Credential hygiene

Keep client_secret values in a secrets manager or equivalent secure runtime configuration.
Treat access tokens and client-certificate private keys as short-lived sensitive credentials and never log them.
Do not hard-code tokens or client secrets in source or build artifacts.
Prefer the SDKs or a centralized HTTP client wrapper so bearer-token attachment happens in one place and the mTLS edge requirements stay consistent.

Relationship to other pages

Endpoints — the per-route contract.
SDKs — idiomatic clients for Rust, Go, and Python.
Platform API — overview of the metadata-only control plane.