Skip to main content

​
Overview

Dokploy API supports two authentication methods:
  1. API Keys - Recommended for programmatic access and automation
  2. Session Cookies - Used by the web interface
For most API integrations, API Keys are the preferred method as they provide secure, programmatic access without requiring interactive login.

​
API Key Authentication

​
Creating an API Key

To create an API key:
  1. Log in to your Dokploy dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Provide a name and select the organization
  5. Copy the generated key (you won’t be able to see it again)
Store your API key securely. Treat it like a password - anyone with access to your API key can perform actions on your behalf.

​
Using API Keys

Include your API key in the X-API-Key header with every request: 
curl -X GET 'https://your-dokploy-instance.com/api/project.all' \
  -H 'X-API-Key: your-api-key-here'

​
API Key Format

API keys are generated with metadata that includes:
  • Organization ID: Links the key to a specific organization
  • User ID: Associates actions with your user account
  • Creation timestamp: Tracks when the key was created

​
API Key Permissions

API keys inherit the permissions of the user who created them. The key has access to:
  • All resources within the associated organization
  • The same role-based permissions as the creating user
  • Only the organization specified during key creation
Session cookies are primarily used by the Dokploy web interface. This method is less common for API integrations but may be useful for custom web applications.

​
How It Works

  1. User logs in through the web interface
  2. Server creates a session and returns a session cookie
  3. Browser automatically includes the cookie in subsequent requests

​
Session Configuration

Sessions in Dokploy have the following properties:
  • Expiry: 3 days (259,200 seconds)
  • Update Age: 24 hours (86,400 seconds)
  • Security: HTTP-only cookies with SameSite protection

​
Authentication Flow

​
API Key Validation Process

When you make a request with an API key:

​
Implementation Details

The authentication system (packages/server/src/lib/auth.ts) handles:
  1. API Key Verification
    • Validates the key exists and is active
    • Retrieves associated user and organization
    • Checks user membership in the organization
  2. Session Creation
    • Creates a mock session context for the request
    • Injects organization and user information
    • Applies role-based access controls

​
Making Authenticated Requests

​
Example: Get All Projects

curl -X GET 'https://your-dokploy-instance.com/api/project.all' \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json'

​
Example: Create an Application

curl -X POST 'https://your-dokploy-instance.com/api/application.create' \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-app",
    "appName": "my-app",
    "description": "My awesome application",
    "environmentId": "env-123"
  }'

​
Error Handling

​
Authentication Errors

401 Unauthorized Occurs when:
  • API key is missing
  • API key is invalid or expired
  • API key doesn’t exist in the database
{
  "error": {
    "message": "Unauthorized",
    "code": "UNAUTHORIZED"
  }
}
403 Forbidden Occurs when:
  • User lacks permissions for the requested resource
  • Organization access is denied
  • Resource belongs to a different organization
{
  "error": {
    "message": "Insufficient permissions",
    "code": "FORBIDDEN"
  }
}

​
Security Best Practices

  • Never commit API keys to version control
  • Use environment variables or secret management systems
  • Rotate keys regularly
  • Delete unused keys immediately
  • Always use HTTPS for API requests
  • Never send API keys over unencrypted connections
  • Configure your Dokploy instance with SSL certificates
  • Create separate API keys for different applications
  • Use the principle of least privilege
  • Monitor API key usage regularly
  • Add client-side rate limiting to prevent abuse
  • Handle 429 (Too Many Requests) responses gracefully
  • Implement exponential backoff for retries

​
Organization Context

Each API key is associated with a specific organization. All API requests using that key operate within the context of that organization: 
// API key metadata structure
{
  "organizationId": "org-abc123",
  "userId": "user-xyz789"
}
This means:
  • You can only access resources within the associated organization
  • Multi-organization setups require separate API keys per organization
  • Organization membership and roles are enforced for all requests

​
Next Steps

API Overview

Learn about the API architecture and available endpoints

Application Management

Start managing applications via the API

Docker Operations

Control containers and images programmatically

Project API

Manage projects and environments

Build docs developers (and LLMs) love

Get started for freeTalk to us