Authentication

Overview

Dark Matter supports multiple authentication methods to suit different integration patterns. API keys are used for server-to-server and service account flows; OAuth 2.0 is used for user-delegated access. Choose the method that matches your use case and security requirements.

API keys

API keys provide simple, long-lived authentication for server-side integrations. Include the key in the Authorization header as Bearer <api_key>. API keys are scoped to an environment and can be restricted by permission. Rotate keys periodically and never expose them in client-side code.

OAuth 2.0

OAuth 2.0 enables user-delegated access for applications that act on behalf of end users. Use the authorization code flow with PKCE for web and mobile apps. Tokens are short-lived; use refresh tokens to obtain new access tokens without re-prompting the user.

Service accounts

Service accounts are non-human identities used for automated workflows, batch jobs, and system-to-system integration. They authenticate with API keys or client credentials. Service accounts have explicit permission sets and should be used when no human user context is required.

Token lifecycle

Access tokens expire after a defined period; refresh tokens extend the session. Revoked tokens are invalid immediately. Monitor token usage and implement graceful handling of 401 responses. Use token refresh logic to minimize user re-authentication.

Best practices

Store API keys and secrets in secure vaults, never in source code or environment files committed to version control. Use least-privilege permissions. Rotate credentials on a schedule and immediately if compromise is suspected. Prefer OAuth for user-facing apps and API keys for backend services.