OAuth Client Overview
The OAuth Client API provides endpoints for managing OAuth 2.0 client applications that can authenticate against your Informer instance. This enables third-party applications, CLI tools, and device-based clients to securely access Informer APIs using standard OAuth 2.0 flows.
Features
- Client CRUD - Create, manage, and revoke OAuth client applications
- Secret Management - Rotate client secrets with bcrypt hashing
- Authorization Code Flow - Standard OAuth 2.0 authorization code grant with PKCE support
- Device Authorization Flow - For input-constrained devices (CLI tools, smart displays)
- Refresh Tokens - Optional refresh token support with rotation and replay detection
- Scope-Based Access - Granular scope system controlling API access per token
- Templates - Pre-built client templates for Informer CLI and Informer GO
Authentication
All OAuth Client management endpoints require superuser access and the token API feature to be enabled. The OAuth protocol endpoints (authorize, token exchange) use standard OAuth authentication.
Permissions
| Operation | Required |
|---|---|
| List clients | Superuser + token API feature |
| Create client | Superuser + token API feature |
| Edit client | Superuser + token API feature |
| Delete client | Superuser |
| Manage secrets | Superuser + token API feature |
| Revoke tokens | Superuser + token API feature |
OAuth Scopes
Scopes control what APIs an issued token can access:
| Scope | Description |
|---|---|
read:dataset | Read-only dataset access |
write:dataset | Read/write dataset access |
read:report | Read-only report access |
write:report | Read/write report and query access |
read:profile | Read-only user profile access |
write:profile | Read/write user profile access |
read:global | Read-only access to any endpoint |
write:global | Full access to any endpoint |
Token Lifecycle
- Authorization Code - Single-use, expires in 60 seconds (stored in Redis)
- Access Token - JWT, 15-minute expiration when refresh tokens are enabled, unlimited otherwise
- Refresh Token - JWT, 30-day expiration, rotates on each use with replay detection
- Token Record - Database record, expires after 30 days when refresh tokens are enabled
Built-in Clients
Informer ships with template definitions for two built-in clients:
| Client | Client ID | PKCE | Description |
|---|---|---|---|
| Informer CLI | a6bd8f0f72b2c3275ff6 | Yes | Command-line interface |
| Informer GO | 7de183326832a18237b4 | Yes | Desktop/mobile application |
Next Steps
- Core CRUD - Client management operations
- Secrets - Client secret management
- Authorization - OAuth authorization code flow
- Device Flow - Device authorization flow