Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/everruns/everruns/llms.txt

Use this file to discover all available pages before exploring further.

Everruns supports flexible authentication modes for different deployment scenarios, from no authentication in local development to full OAuth-based authentication in production.

​
Authentication Modes

The platform supports four authentication modes controlled by the AUTH_MODE environment variable:

​
None Mode

AUTH_MODE=none
No authentication required. All requests use a well-known anonymous user. Suitable for local development.

​
Admin Mode

AUTH_MODE=admin
Single admin user via environment variables. Basic access control for local development.

​
Full Mode

AUTH_MODE=full
Complete authentication with user registration, OAuth, and API keys. Suitable for production deployments.

​
External Mode

AUTH_MODE=external
Authentication managed by third-party provider (e.g., PropelAuth, Auth0, Clerk). API key authentication is still supported.

​
Authentication Methods

When authentication is enabled, you can authenticate requests using one of three methods:

​
1. Bearer Token (JWT)

Include your access token in the Authorization header: 
Authorization: Bearer <access_token>
Example: 
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.example.com/v1/agents
Token Characteristics:
  • Access tokens are short-lived (default: 15 minutes)
  • Refresh tokens are stored in the database for revocation
  • Tokens include user ID, email, name, and roles
Access tokens expire after 15 minutes by default. Use the refresh endpoint to obtain a new token pair.

​
2. API Key

API keys provide long-lived authentication for programmatic access: 
Authorization: <api_key>
Or with explicit prefix: 
Authorization: ApiKey <api_key>
Example: 
curl -H "Authorization: evr_1234567890abcdef" \
  https://api.example.com/v1/agents
API Key Characteristics:
  • Prefixed with evr_ for identification
  • Full key shown only at creation time
  • Stored hashed using SHA-256
  • Support scopes and expiration
  • Ideal for server-to-server communication
API keys are shown only once at creation. Store them securely - they cannot be retrieved later.
Used by the web UI for browser-based authentication:
  • access_token cookie contains the JWT
  • refresh_token cookie (HTTP-only, secure) for token renewal
The UI automatically handles token refresh when access tokens expire.

​
Managing API Keys

​
Create API Key

POST /v1/auth/api-keys
Request: 
{
  "name": "Production Server",
  "expires_at": "2025-12-31T23:59:59Z"  // optional
}
Response: 
{
  "id": "01933b5a-0000-7000-8000-000000000001",
  "key": "evr_1234567890abcdef",  // shown only once
  "name": "Production Server",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2025-12-31T23:59:59Z"
}

​
List API Keys

GET /v1/auth/api-keys
Response: 
[
  {
    "id": "01933b5a-0000-7000-8000-000000000001",
    "name": "Production Server",
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2025-12-31T23:59:59Z",
    "last_used_at": "2024-01-20T14:22:00Z"
  }
]

​
Delete API Key

DELETE /v1/auth/api-keys/{key_id}

​
OAuth Providers

In full authentication mode, OAuth2 is supported with the following providers:

​
Google OAuth

  • Uses OpenID Connect
  • Requires email and profile scopes
  • Supports email domain restrictions

​
GitHub OAuth

  • Requires user:email and read:user scopes
  • Supports account linking by email
Accounts are automatically linked when the same email is used across different OAuth providers.

​
Token Refresh

When your access token expires, use the refresh endpoint: 
POST /v1/auth/refresh
Request (programmatic clients): 
{
  "refresh_token": "your_refresh_token"
}
Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "new_refresh_token",
  "expires_in": 900
}
Refresh tokens are rotated on each use. The old token is invalidated when a new pair is issued.

​
Authentication Configuration

Query the current authentication configuration: 
GET /v1/auth/config
Response: 
{
  "mode": "full",
  "password_enabled": true,
  "signup_enabled": true,
  "oauth_providers": ["google", "github"]
}

​
Current User Information

Retrieve information about the authenticated user: 
GET /v1/auth/me
Response: 
{
  "id": "01933b5a-0000-7000-8000-000000000001",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "admin",
  "created_at": "2024-01-15T10:30:00Z"
}

​
Security Considerations

​
Token Storage

  • Store access tokens securely in memory
  • Never expose tokens in URLs or logs
  • Refresh tokens should be stored in secure, HTTP-only cookies for browser clients

​
API Key Security

  • API keys are hashed using SHA-256 before storage
  • Full key is displayed only once at creation
  • Treat API keys like passwords - never commit them to source control
  • Rotate keys regularly and delete unused keys

​
Password Requirements

  • Minimum 8 characters
  • Hashed using Argon2id with secure defaults

​
CORS Configuration

For cross-origin requests, configure allowed origins: 
CORS_ALLOWED_ORIGINS=https://app.example.com,https://dashboard.example.com

​
Error Responses

See the Error Handling page for authentication-related error codes:
  • 401 Unauthorized - Missing or invalid credentials
  • 403 Forbidden - Valid credentials but insufficient permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us