---
title: Authentication | Docs | Lattix
description: 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.
source: "https://lattix.io/docs/api/authentication/"
content-type: text/markdown
---

# Authentication | Docs | Lattix

Platform API

# 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

1. Provision a tenant-scoped confidential client in the shared platform issuer.
2. Request an access token for the `api://lattix-platform-api` audience.
3. When `proof_of_possession=mtls`, present the matching client certificate at the public TLS edge.
4. Present `Authorization: Bearer <access_token>` on `/v1/sdk/*` calls.
5. 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

- [MCP authentication](https://lattix.io/docs/mcp/authentication/), dedicated MCP audience, tenant binding, and secure exchange to a separate Platform API token.
- [Endpoints](https://lattix.io/docs/api/endpoints/), the per-route contract.
- [SDKs](https://lattix.io/docs/sdks/): idiomatic clients for Rust, Go, and Python.
- [Platform API](https://lattix.io/docs/api/), overview of the metadata-only control plane.

[Platform API The Lattix Platform API, a metadata-only HTTP control plane for embedded enforcement. Eight public /v1/sdk/\* routes, JSON request/response, sender-constrained OAuth/OIDC bearer-token access, and a published OpenAPI contract.](https://lattix.io/docs/api/) [Endpoints Reference for the eight /v1/sdk/\* routes: discovery, planning, registration, and evidence ingestion.](https://lattix.io/docs/api/endpoints/)