API Authentication

API key authentication

The primary authentication method for the GOVERN API is a Bearer token:

curl https://api.govern.archetypal.ai/v1/assessments \
  -H "Authorization: Bearer gvn_live_xxxxxxxxxxxx" \
  -H "X-Govern-Org-Id: org_xxxxxxxxxxxx"

API key types

Prefix	Type	Use for
gvn_live_	Production	All production assessments and API calls
gvn_test_	Test	CI/CD, development — events not stored in audit trail
gvn_admin_	Admin	Organization management, policy updates

Creating API keys

1. Navigate to govern.archetypal.ai
2. Settings → API Keys → New Key
3. Choose key type and optional expiry
4. Copy the key (shown only once)

Or via API (requires an existing admin key):

curl -X POST https://api.govern.archetypal.ai/v1/api-keys \
  -H "Authorization: Bearer gvn_admin_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Probe",
    "type": "live",
    "description": "Used by the production GOVERN Probe"
  }'

Key rotation

# Create new key
curl -X POST https://api.govern.archetypal.ai/v1/api-keys ...

# Update your deployment with the new key

# Revoke the old key
curl -X DELETE https://api.govern.archetypal.ai/v1/api-keys/key_xxxx \
  -H "Authorization: Bearer gvn_admin_xxxx"

JWT authentication (SSO)

For organizations using SSO (Okta, Azure AD, Google Workspace), users can authenticate via JWT:

# Exchange SSO token for GOVERN JWT
curl -X POST https://api.govern.archetypal.ai/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"sso_token": "eyJhbG..."}'

# Response
{
  "token": "eyJhbGciOiJSUzI1NiJ9...",
  "expires_at": "2026-04-12T16:00:00Z"
}

# Use JWT
curl https://api.govern.archetypal.ai/v1/events \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

JWTs expire after 1 hour. Refresh before expiry using POST /v1/auth/token/refresh.

Service account authentication

For automated systems and CI/CD pipelines, create a service account:

curl -X POST https://api.govern.archetypal.ai/v1/service-accounts \
  -H "Authorization: Bearer gvn_admin_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-actions",
    "permissions": ["assess:create", "events:read"],
    "ip_allowlist": ["4.4.4.0/24"]
  }'

Service accounts have scoped permissions and can be restricted to specific IP ranges.

Permission scopes

Scope	Description
assess:create	Create assessments (SDK/Probe)
events:read	Read assessment events and audit trail
policy:read	Read governance policy
policy:write	Update governance policy
probes:read	Read probe status
probes:write	Configure probes
webhooks:read	Read webhook configurations
webhooks:write	Create and modify webhooks
reports:read	Read reports and exports
admin:*	All permissions

Security best practices

• Use gvn_test_ keys in CI/CD (events not logged)
• Rotate production keys every 90 days
• Scope service account permissions to minimum required
• Enable IP allowlisting for service accounts in known environments
• Store keys in secrets managers (AWS Secrets Manager, HashiCorp Vault, GitHub Secrets)
• Never log or print API keys

Authentication errors

HTTP Status	Code	Meaning
401	unauthorized	Missing or invalid API key
401	token_expired	JWT has expired
403	insufficient_permissions	Key does not have required scope
403	ip_not_allowed	Request from IP not in allowlist