api keys

{ "apikeys_integrations": { "title": "API Keys & OAuth", "description": "Generate API keys or OAuth clients to provide secure access to your platform for external applications", "help_articles": [ "getting-started-with-integrations" ], "sections": { "overview": { "title": "About API Authentication", "content": "The Notarial platform supports two authentication methods for API access: API Keys (simple) and OAuth 2.0 Client Credentials (enterprise). Choose based on your security requirements." }, "authentication_methods": { "title": "Authentication Methods", "methods": { "api_key": { "title": "API Key Authentication", "description": "Simple header-based authentication using X-API-Key header. Best for quick integrations and internal tools.", "format": "X-API-Key: notary<random32_characters>", "use_cases": ["Internal scripts", "Simple integrations", "Development/testing"] }, "oauth": { "title": "OAuth 2.0 Client Credentials", "description": "Standard OAuth 2.0 flow with access tokens. Best for production applications with enhanced security.", "endpoint": "/api/oauth/token", "use_cases": ["Server-to-server integration", "Mobile apps", "Enterprise applications"] }, "session": { "title": "Session Authentication", "description": "Cookie-based authentication for web applications that authenticate users via login.", "use_cases": ["Web dashboards", "Admin panels", "User-facing apps"] } } }, "scopes": { "title": "Permission Scopes", "scopes": { "read": { "title": "Read Access", "description": "View data including orders, companies, invoices, notaries, and journal entries" }, "write": { "title": "Write Access", "description": "Create and modify records across all modules" }, "delete": { "title": "Delete Access", "description": "Permanently delete records (use with caution)" }, "admin": { "title": "Admin Access", "description": "Full system access including settings, user management, and configuration" } } }, "api_key_format": { "title": "API Key Format", "format": "notary<32_random_characters>", "example": "notary_xK9mP2vR4nQ8sT6wY1hJ3fD5cZ7bN9", "note": "Keys are SHA-256 hashed before storage. The full key is only shown once during creation." }, "oauth_flow": { "title": "OAuth 2.0 Flow", "steps": [ { "step": "1. Create OAuth Client", "description": "Generate client_id and client_secret from Integrations dashboard" }, { "step": "2. Request Token", "description": "POST to /api/oauth/token with client credentials" }, { "step": "3. Receive Access Token", "description": "Get bearer token with 1-hour expiration" }, { "step": "4. Make API Requests", "description": "Include Authorization: Bearer <token> header" }, { "step": "5. Refresh as Needed", "description": "Request new token when current expires" } ] }, "security": { "title": "Security Features", "features": { "hashing": { "title": "SHA-256 Hashing", "description": "API keys are hashed before storage, never stored in plain text" }, "token_expiration": { "title": "Token Expiration", "description": "OAuth access tokens expire after 1 hour for security" }, "rate_limiting": { "title": "Rate Limiting", "description": "Configurable rate limits per API key or OAuth client" }, "audit": { "title": "Audit Logging", "description": "All API access logged to audit_log table with IP, user agent, and response details" }, "scope_enforcement": { "title": "Scope Enforcement", "description": "Permissions validated on every request based on assigned scopes" } } }, "quick_actions": { "title": "Key Management", "actions": [ { "action": "Generate API Key", "description": "Create a new API key with custom scopes and expiration" }, { "action": "Create OAuth Client", "description": "Generate OAuth credentials for server-to-server integration" }, { "action": "View Usage Analytics", "description": "Check API usage statistics and performance metrics" }, { "action": "Revoke Access", "description": "Immediately invalidate an API key or OAuth client" } ] }, "best_practices": { "title": "Best Practices", "tips": [ "Use OAuth 2.0 for production integrations requiring enhanced security", "Use API keys for simple integrations and internal tools", "Apply principle of least privilege when assigning scopes", "Rotate API keys every 90 days", "Store secrets in environment variables or secure vaults", "Monitor audit logs for unusual API usage patterns", "Implement retry logic with exponential backoff for rate limits" ] } } } }