Authentication

All API endpoints require authentication. Nagovori supports two methods:

API Keys

API keys are the recommended method for server-to-server integrations. Create keys from your Profile.

Format: nag_ followed by 32 hex characters (e.g., nag_a1b2c3d4e5f67890abcdef1234567890).

Usage: Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer nag_YOUR_API_KEY

Security

• Keys are hashed before storage — Nagovori never stores the raw key
• Each key has a visible prefix (nag_xxxx) for identification
• Revoked keys are immediately invalidated
• Keys can be scoped to specific operations (coming soon)

Best Practices

• Never commit API keys to version control
• Use environment variables: NAGOVORI_API_KEY
• Rotate keys periodically
• Use separate keys for development and production
• Revoke unused keys

JWT (OAuth2)

For web applications, Nagovori uses JWT tokens issued by the identity provider (Zitadel). This is what the web interface uses internally.

JWT tokens are obtained through the standard OIDC authorization code flow. Contact support if you need OAuth2 integration.

Error Responses

Authentication failures return 401 Unauthorized:

{
  "error": "invalid api key"
}

Common authentication errors:

Error	Cause
missing Authorization header	No Authorization header provided
invalid Authorization header format	Header must be Bearer <token>
invalid api key	Key not found or hash mismatch
api key has been revoked	Key was revoked via the dashboard
api key has expired	Key passed its expiration date
invalid token	JWT is malformed or signature invalid
token expired	JWT has expired