# auth.md

Veraius agent authentication and registration.

## Audience

Agents and MCP clients that need bearer access to Veraius APIs (`https://web.veraius.com`).

## Human / browser

- Sign in: [https://web.veraius.com/login](https://web.veraius.com/login) (OIDC via Keycloak; break-glass local form: `/login?local=1`)
- Issuer (authorization server): `https://sso.veraius.com/realms/veraius`
- Discovery: [https://sso.veraius.com/realms/veraius/.well-known/openid-configuration](https://sso.veraius.com/realms/veraius/.well-known/openid-configuration)

## Machine / API

1. Register or provision a Keycloak client (`client_credentials` for services, authorization code + PKCE for interactive agents). Dynamic registration (when enabled on the realm): `https://sso.veraius.com/realms/veraius/clients-registrations/openid-connect`.
2. Obtain tokens from Keycloak token endpoint: `https://sso.veraius.com/realms/veraius/protocol/openid-connect/token`.
3. Call Veraius APIs with `Authorization: Bearer <access_token>`.
4. Protected-resource metadata: [https://web.veraius.com/.well-known/oauth-protected-resource](https://web.veraius.com/.well-known/oauth-protected-resource)
5. Authorization-server metadata (includes `agent_auth`): [https://web.veraius.com/.well-known/oauth-authorization-server](https://web.veraius.com/.well-known/oauth-authorization-server)
6. API catalog: [https://web.veraius.com/.well-known/api-catalog](https://web.veraius.com/.well-known/api-catalog)
7. MCP server card: [https://web.veraius.com/.well-known/mcp/server-card.json](https://web.veraius.com/.well-known/mcp/server-card.json)
8. Health: [https://web.veraius.com/health/ready](https://web.veraius.com/health/ready)

## agent_auth

See `agent_auth` on [https://web.veraius.com/.well-known/oauth-authorization-server](https://web.veraius.com/.well-known/oauth-authorization-server):
`register_uri`, `identity_types_supported` (`service_auth`, `anonymous`), credential types, `claim_uri`, and `revocation_uri`.

### Anonymous

Public discovery documents (`/auth.md`, `/.well-known/*`, `/health/*`) require no credential. Authenticated APIs reject anonymous callers with `401`.

## Scopes

`openid`, `profile`, `email` (Keycloak realm `veraius`).