Authentication

DevDocs authentication should make the public docs surface easy to read while keeping publishing, domain, and API-execution controls protected.

Identity model

DevDocs uses the shared DevDocs account system for human access. The docs site can stay public, but protected surfaces should know:

• the signed-in user
• the active organization
• the user role in that organization
• whether the route is public, preview-only, or operator-only

API access

Core API calls should use bearer credentials, not long-lived secrets embedded in docs pages.

Playground credential rules

The OpenAPI playground should treat credentials as sensitive input:

• never persist raw API keys in the docs database in V1
• mask tokens in the UI after entry
• redact Authorization, cookies, and secret-like headers from logs
• prefer same-origin demo execution until the proxy is hardened
• require an explicit allowlist before proxying external targets

Failure behavior

Authentication failures should be easy to diagnose without leaking secrets:

• 401 means the caller needs to authenticate
• 403 means the caller is authenticated but lacks permission
• 404 can be used when revealing the existence of a resource would leak tenancy
• 429 means the caller should retry later

Read next

• Authorization Controls
• Errors
• API References