API Authentication

Odin Scan uses a layered authentication model combining JWT-based authentication for the dashboard and API keys for programmatic access. All API endpoints that access user data require authentication.

Authentication Methods

JWT Authentication (Dashboard and Frontend)

The primary authentication method uses JSON Web Tokens (JWT) issued by Clerk. When you sign in through the Odin Scan dashboard, Clerk issues a signed JWT that the frontend includes with every API request.

How it works:

1. You authenticate via the dashboard (email/password, GitHub OAuth, or Google OAuth).
2. Clerk issues a signed JWT containing your user claims.
3. The frontend sends this token with every request.
4. The API validates the token signature against Clerk’s JWKS endpoint.

Authorization: Bearer <jwt-token>

JWT tokens are short-lived and automatically refreshed by the frontend. You do not need to manage JWT tokens directly unless you are building a custom integration.

API Key Authentication (Programmatic Access)

For scripts, CI/CD pipelines, and third-party integrations, Odin Scan supports API key authentication.

API key format:

odin_sk_<random-string>

All API keys use the odin_sk_ prefix followed by a cryptographically random string.

Using an API key:

You can pass the key in either of two headers:

Authorization: Bearer odin_sk_abc123def456...

api-key: odin_sk_abc123def456...

Both methods are equivalent. Use whichever is more convenient for your tooling.

Creating API Keys

1. Sign in to the Odin Scan dashboard.
2. Navigate to Settings > API Keys.
3. Click Create New Key.
4. Give the key a descriptive name (e.g., “GitHub Actions - Production”).
5. Copy the key immediately – it will not be displayed again.

Revoking API Keys

To revoke a key:

1. Go to Settings > API Keys.
2. Find the key you want to revoke.
3. Click Revoke.

Revoked keys stop working immediately. Any requests using a revoked key receive a 401 Unauthorized response.

Authentication Errors

Example error response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token"
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "requestId": "req-abc123"
}

Security Best Practices

• Never commit API keys to version control. Use environment variables or a secrets manager instead.
• Rotate keys regularly. Create a new key, update your integrations, then revoke the old one.
• Use the minimum scope necessary. If you only need read access, do not use a key with write permissions.
• Store keys in a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or your CI/CD platform’s built-in secrets storage (e.g., GitHub Actions secrets).
• Monitor key usage. Review audit logs periodically for unexpected activity.
• Revoke compromised keys immediately. If a key is accidentally exposed, revoke it and create a replacement.

Session Management

Behind the scenes, the API caches validated user sessions in Redis for 15 minutes. This reduces the overhead of repeated JWT validation on frequent API calls. Sessions are automatically invalidated on logout or token expiry.

Note: Multi-factor authentication (MFA) is supported through Clerk. Enable MFA in your account settings for an additional layer of security. See the Clerk documentation for configuration details.

Next Steps

• REST API Reference – full endpoint documentation
• Rate Limits – understand request limits by subscription tier