v1.2.2

Developer Authentication

Choose an identity flow before calling AIGP. Authentication identifies the caller; organization and project context scope the request, but do not grant authority.

Choose Flow

Situation	Use	Do not use
Private local experimentation	Development authentication and approved headers.	Shared or production environments.
Local API request with Keycloak	The local short-lived service-account token below.	A copied password or a committed token.
Studio, VS Code, or another person-operated client	Browser OIDC sign-in.	A service-account secret in client configuration.
Backend, CI, or scheduled work	A dedicated confidential workload client from a secret manager.	The local walkthrough or MCP service identity.

What AI_GOVERNANCE_TOKEN means in examples

AI_GOVERNANCE_TOKEN is a shell variable used by REST examples in this documentation. It is not an AIGP server setting, and the guided CLI deliberately ignores it. It should hold one short-lived access token only for the process that makes the request.

Local Development Mode

A server configured with AI_GOVERNANCE_AUTH_MODE=development does not validate bearer tokens. It derives the actor from the approved development identity path and accepts the actor header below. Configure this on the server before starting it; exporting the value in a separate client shell does not reconfigure an already-running Keycloak-backed stack.

bash

curl --fail-with-body http://localhost:8000/api/v1/context \
  -H 'X-AI-Governance-Actor-Id: local-admin' \
  -H 'X-AI-Governance-Organization-Id: org_default' \
  -H 'X-AI-Governance-Project-Id: project_default'

Local only

Development mode is not an authentication mechanism. Never enable it in a shared, staging, or production deployment.

Local Keycloak and curl

Use this when the local stack runs in Keycloak mode and a tutorial asks for AI_GOVERNANCE_TOKEN. Local startup creates the ignored .env.oauth.generated file for its dedicated walkthrough client. This exchanges its client credentials for one short-lived token without writing that token to disk.

bash

./servers.sh

set -a
. ./.env.oauth.generated
set +a

export AI_GOVERNANCE_API_URL=http://localhost:8000
export AI_GOVERNANCE_TOKEN="$(uv run python -c '
from ai_governance.oauth import access_token_from_environment
token = access_token_from_environment()
assert token, "AI_GOVERNANCE_OAUTH_* credentials are required"
print(token)
')"
export AI_GOVERNANCE_ORGANIZATION_ID=org_default
export AI_GOVERNANCE_PROJECT_ID=project_default

curl --fail-with-body "$AI_GOVERNANCE_API_URL/api/v1/context" \
  -H "Authorization: Bearer $AI_GOVERNANCE_TOKEN" \
  -H "X-AI-Governance-Organization-Id: $AI_GOVERNANCE_ORGANIZATION_ID" \
  -H "X-AI-Governance-Project-Id: $AI_GOVERNANCE_PROJECT_ID"

unset AI_GOVERNANCE_TOKEN

The returned context must show the intended tenant and permissions. A valid token can still receive 403 when its subject lacks membership or the required role.

Interactive Users

Studio and person-operated MCP clients should use browser OIDC sign-in. The identity provider issues and refreshes the user's short-lived token, so audit records identify the person rather than a shared service account. For VS Code and native MCP setup, follow the Streamable HTTP browser-sign-in flow.

Production Workloads and CI

Give every backend, agent runtime, and CI job its own least-privilege confidential client. Store its credentials in the deployment secret manager and provide the generic workload-neutral configuration at runtime:

bash

AI_GOVERNANCE_OAUTH_TOKEN_URL=https://issuer.example/realms/ai-governance/protocol/openid-connect/token
AI_GOVERNANCE_OAUTH_CLIENT_ID=claims-runtime
AI_GOVERNANCE_OAUTH_CLIENT_SECRET=provided-by-your-secret-manager

Exchange those credentials in memory immediately before a request or use an OAuth library that refreshes them. Do not persist the resulting access token as a deployment secret. The workload's validated token subject establishes identity; organization and project headers select only a scope that subject is allowed to use.

Guided CLI

The governed-replay CLI loads AI_GOVERNANCE_OAUTH_* and exchanges a short-lived token itself. Do not export AI_GOVERNANCE_TOKEN for this path: it is intentionally ignored so a stale shell token cannot replace the configured workload identity. Supply a pre-obtained token only with the explicit --token option. See the Governed Replay Walkthrough.

Token-handling Rules

Never commit .env.oauth.generated, client secrets, or access tokens.
Never print tokens in CI logs, terminal transcripts, tickets, or screenshots.
Use separate human and workload identities; do not make a shared token stand in for a person.
Use the local MCP and walkthrough clients only for local development; production workloads need their own identity and tenant membership.