Authentication Overview

Overview

The platform supports multiple authentication methods to accommodate different integration patterns. Whether you are building a server-side integration, a single-page application, or a mobile app, there is an authentication method suited to your use case.

All API requests must be authenticated. Unauthenticated requests will receive a 401 Unauthorized response.

Authentication Methods

API Keys

API keys are the simplest authentication method. They are ideal for server-side integrations where the key can be stored securely and never exposed to end users.

Generating an API Key

Using API Keys

Include the API key in the Authorization header of every request:

curl -X GET "https://api.example.com/v1/users" \
  -H "Authorization: Bearer pk_live_abc123def456ghi789"

In a TypeScript application:

const API_KEY = process.env.API_KEY;

const response = await fetch("https://api.example.com/v1/users", {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
});

const data = await response.json();

API Key Permissions

Each API key can be scoped to specific permissions:

To create a read-only key, select only the read permission when generating the key.

OAuth 2.0

OAuth 2.0 is the recommended authentication method for applications that act on behalf of users. It provides a secure authorization flow without exposing user credentials to your application.

Authorization Code Flow

The Authorization Code flow is a five-step process for obtaining an access token:

Token Response

A successful token exchange returns the following JSON:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_abc123def456",
  "scope": "read write"
}

Refreshing Tokens

Access tokens expire after the duration specified by expires_in (in seconds). Use the refresh token to obtain a new access token without requiring user interaction:

curl -X POST "https://auth.example.com/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=rt_abc123def456" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

JWT Tokens

JSON Web Tokens (JWT) provide a compact, self-contained method for transmitting authentication claims between services. JWTs are commonly used in microservice architectures where each service needs to verify the caller’s identity without making a database lookup.

Token Structure

A JWT consists of three parts separated by dots:

header.payload.signature

Decoding a JWT

The payload of a typical JWT contains:

{
  "sub": "user_123",
  "name": "Alice Johnson",
  "role": "admin",
  "iat": 1720000000,
  "exp": 1720003600,
  "iss": "https://auth.example.com"
}

Validating JWTs

When receiving a JWT, always validate the following:

1. Signature — Verify the signature using the issuer’s public key
2. Expiration — Reject tokens where exp is in the past
3. Issuer — Confirm iss matches your expected authentication server
4. Audience — If present, verify aud matches your service identifier

import jwt from "jsonwebtoken";

const PUBLIC_KEY = process.env.JWT_PUBLIC_KEY;

function validateToken(token: string) {
  try {
    const decoded = jwt.verify(token, PUBLIC_KEY, {
      algorithms: ["RS256"],
      issuer: "https://auth.example.com",
    });
    return decoded;
  } catch (error) {
    throw new Error(`Token validation failed: ${error.message}`);
  }
}

Session Management

Session-based authentication is suitable for traditional web applications where the server maintains session state. After a successful login, the server creates a session and returns a session token as an HTTP cookie.

Session Lifecycle

Session Configuration

Sessions are configured with the following defaults:

const sessionConfig = {
  maxAge: 86400,         // 24 hours in seconds
  idleTimeout: 1800,     // 30 minutes in seconds
  secure: true,          // HTTPS only
  httpOnly: true,        // Not accessible via JavaScript
  sameSite: "strict",    // CSRF protection
  domain: ".example.com" // Shared across subdomains
};

Best Practices

Follow these security best practices for all authentication methods:

Token Storage

• Server-side applications — Store tokens in environment variables or a secrets manager. Never hard-code tokens in source files.
• Browser applications — Store tokens in httpOnly cookies. Avoid localStorage and sessionStorage, which are vulnerable to XSS attacks.
• Mobile applications — Use the platform’s secure keychain (iOS Keychain, Android Keystore).

Token Rotation

• Rotate API keys periodically (every 90 days is recommended)
• Implement refresh token rotation where a new refresh token is issued with each access token refresh
• Revoke old tokens promptly when rotating

Monitoring

• Log all authentication events (login, logout, token refresh, failed attempts)
• Set up alerts for unusual patterns (multiple failed logins, logins from new locations)
• Monitor for leaked credentials in public repositories using automated scanning tools

Secure Communication

• Always use HTTPS for all API communication
• Implement certificate pinning in mobile applications
• Use TLS 1.2 or higher; reject connections on older protocols

Least Privilege

• Grant the minimum permissions necessary for each API key or OAuth scope
• Create separate keys for different environments (development, staging, production)
• Audit permissions regularly and revoke unused access