Overview
Authentication
Learn how to authenticate with the Docimal API using JWT tokens and API keys.
Overview
Docimal supports two authentication methods: JWT Bearer tokens for user-based access (management endpoints), and public API keys for chatbot interactions (public endpoints). Choose the method based on your integration type.
JWT Authentication
For management endpoints, authenticate with a Bearer token in the Authorization header: Authorization: Bearer <token>. Obtain tokens through the login endpoint (POST /auth/login) with email and password. Tokens include tenant and user context and expire after a configurable period. Use the refresh token endpoint to obtain new access tokens without re-authenticating.
Public API Keys
For chatbot-facing endpoints (getting config, starting sessions, sending messages), use a public API key. Generate keys from the Chatbot > Deploy tab in the dashboard. Include the key in the X-API-Key header. Keys are prefixed with dcml_pk_ followed by 48 hex characters and are scoped to a specific chatbot. Each key supports domain whitelisting, hourly/daily rate limits, and expiration dates. Keys are validated using a SHA-256 lookup hash and bcrypt verification on the server. Revoke keys immediately if compromised.
OAuth Providers
Docimal supports social login via Google and GitHub OAuth. Initiate the flow with GET /auth/callback/google or /auth/callback/github. After the OAuth provider redirects back, the user receives JWT tokens. This is primarily used for the Docimal dashboard login, not for API integrations.
Security Best Practices
Never expose JWT tokens or secret API keys in client-side code. Use public API keys (dcml_pk_) for browser-based integrations. Rotate tokens regularly. Implement token refresh logic to avoid expired token errors. Store credentials in environment variables, never in source code.