> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuraltrust.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth

> Auth credentials authenticate clients as a consumer — API key, OAuth2, OIDC, or mTLS. Created per gateway and attached to consumers.

An **auth** credential is how a client proves it may act as a
[consumer](/trustgate/concepts/consumers). Credentials are created at the gateway level and
**attached** to one or more consumers, so you can rotate or share them independently of the
consumer itself.

This is distinct from a registry's [target auth](/trustgate/concepts/registries#target-auth),
which is how TrustGate authenticates to the **upstream provider**.

## Auth types

| `type`        | How the client authenticates                                                                         | Routing mode          |
| ------------- | ---------------------------------------------------------------------------------------------------- | --------------------- |
| **`api_key`** | `X-AG-API-Key: ag_…` header                                                                          | inline                |
| **`oauth2`**  | `Authorization: Bearer <jwt>` (or opaque token + introspection) validated against an OAuth2 provider | inline or role\_based |
| **`oidc`**    | `Authorization: Bearer <jwt>` from your IdP; claims select a [role](/trustgate/concepts/roles)       | inline or role\_based |
| **`mtls`**    | Client certificate (or a trusted `X-Forwarded-Client-Cert` header)                                   | inline                |

| Plane   | Consumer auth types         |
| ------- | --------------------------- |
| **LLM** | `api_key`, `oauth2`, `oidc` |
| **MCP** | `oauth2`                    |

A `role_based` LLM consumer carries exactly one identity credential — `oauth2` or `oidc`.

## API keys

API keys are prefixed **`ag_`**. The raw secret is returned **once**, at creation — store
it then. TrustGate only persists a SHA-256 hash; at request time it hashes the inbound key
and compares, so the secret is never recoverable from the gateway.

```bash theme={null}
# create → returns api_key (cleartext) once
POST /v1/gateways/{gateway_id}/auths
{ "name": "my-app-key", "type": "api_key" }

# attach to a consumer
POST /v1/gateways/{gateway_id}/consumers/{id}/auths/{auth_id}
```

## OAuth2 / OIDC / mTLS

JWT- and certificate-based credentials carry a `config` block:

| Type     | Config fields                                                                                                                                   |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `oauth2` | `issuer`, `audiences`, `jwks_url`, `introspection_url`, `client_id`/`secret`, `required_scopes`, `allowed_algorithms`, optional `session_mode`. |
| `oidc`   | `issuer`, `audiences`, `jwks_url`, `public_keys`, `required_scopes`, `allowed_algorithms`, `subject_claim`.                                     |
| `mtls`   | `ca_cert`, `allowed_common_names`, `allowed_dns_names`, `allowed_fingerprints`.                                                                 |

For **`oidc`** credentials on a `role_based` consumer, the validated token's claims are
matched against role [OIDC mappings](/trustgate/concepts/roles) to select the consumer's
routing — this is how identity-based routing works.

For end-to-end, provider-specific setup (custom authorization servers, scopes, group/role
claims, and the exact credential payloads), see the
[Authorization](/trustgate/concepts/authorization/overview) manuals for
[Okta](/trustgate/concepts/authorization/okta) and
[Entra ID](/trustgate/concepts/authorization/entra-id).

## Managing auth

CRUD lives under `/v1/gateways/{gateway_id}/auths`; attach/detach via the consumer's
`…/auths/{auth_id}` sub-resource. See the [Auth API](/trustgate/api/overview).