Authentication - Dokploy

Dokploy uses API key authentication to secure API access. API keys are organization-scoped and can be configured with permissions, rate limits, and expiration dates.

Authentication Methods

Dokploy supports two authentication methods:

API Key Authentication (Recommended for programmatic access)
Session Authentication (Used by the web dashboard)

For API integrations, webhooks, and automation, always use API key authentication.

API Key Authentication

API keys are passed in the x-api-key header with every request:

curl -X POST https://your-dokploy-instance.com/api/trpc/project.all \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json"

How It Works

Generate an API key from the Dokploy dashboard
Include the API key in the x-api-key header
The API validates the key and associates the request with your organization
Rate limits and permissions are enforced based on the key configuration

Creating an API Key

API keys must be created through the Dokploy API by authenticated users.

Create API Key Endpoint

Procedure: user.createApiKey Method: POST Request:

curl -X POST https://your-dokploy-instance.com/api/trpc/user.createApiKey \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "name": "Production API Key",
    "prefix": "prod",
    "expiresIn": 31536000000,
    "metadata": {
      "organizationId": "org_abc123"
    },
    "rateLimitEnabled": true,
    "rateLimitTimeWindow": 60000,
    "rateLimitMax": 100
  }'

Parameters:

Parameter	Type	Required	Description
`name`	string	Yes	Descriptive name for the API key
`prefix`	string	No	Custom prefix for the key (e.g., “prod”, “dev”)
`expiresIn`	number	No	Expiration time in milliseconds from now
`metadata.organizationId`	string	Yes	Organization ID this key belongs to
`rateLimitEnabled`	boolean	No	Enable rate limiting
`rateLimitTimeWindow`	number	No	Time window in milliseconds
`rateLimitMax`	number	No	Max requests per time window
`remaining`	number	No	Initial request limit
`refillAmount`	number	No	Requests to refill
`refillInterval`	number	No	Refill interval in milliseconds

Response:

{
  "result": {
    "data": {
      "id": "key_xyz789",
      "key": "prod_dkp_live_abc123def456...",
      "name": "Production API Key",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

The full API key is only shown once during creation. Store it securely - you won’t be able to retrieve it again.

Using API Keys

Once you have an API key, include it in all API requests:

Example: List All Projects

curl -X GET "https://your-dokploy-instance.com/api/trpc/project.all" \
  -H "x-api-key: prod_dkp_live_abc123def456..."

Example: Create a New Application

curl -X POST "https://your-dokploy-instance.com/api/trpc/application.create" \
  -H "x-api-key: prod_dkp_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "environmentId": "env_abc123",
    "description": "Production application"
  }'

Example: Deploy an Application

curl -X POST "https://your-dokploy-instance.com/api/trpc/application.deploy" \
  -H "x-api-key: prod_dkp_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app_xyz789",
    "title": "Deploy v1.2.0",
    "description": "Production deployment"
  }'

Managing API Keys

List Your API Keys

API keys are returned when fetching user information: Procedure: user.get

curl -X GET "https://your-dokploy-instance.com/api/trpc/user.get" \
  -H "x-api-key: your_api_key_here"

Delete an API Key

Procedure: user.deleteApiKey

curl -X POST "https://your-dokploy-instance.com/api/trpc/user.deleteApiKey" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKeyId": "key_xyz789"
  }'

Deleting an API key immediately revokes access. All requests using the deleted key will fail with a 401 UNAUTHORIZED error.

Rate Limiting

API keys can be configured with rate limiting to prevent abuse and control usage.

Rate Limit Configuration

When creating an API key, you can configure: Time-based Rate Limiting:

rateLimitEnabled: Enable rate limiting
rateLimitTimeWindow: Time window in milliseconds (e.g., 60000 = 1 minute)
rateLimitMax: Maximum requests allowed in the time window

Request Limiting:

remaining: Initial number of requests available
refillAmount: Number of requests to add on each refill
refillInterval: Milliseconds between refills

Example: API Key with Rate Limiting

{
  "name": "Limited API Key",
  "metadata": {
    "organizationId": "org_abc123"
  },
  "rateLimitEnabled": true,
  "rateLimitTimeWindow": 60000,
  "rateLimitMax": 100,
  "remaining": 1000,
  "refillAmount": 100,
  "refillInterval": 3600000
}

This configuration:

Allows 100 requests per minute (time-based)
Starts with 1000 total requests
Refills 100 requests every hour

Security Best Practices

Follow these security practices to protect your API keys and Dokploy instance.

1. Store Keys Securely

Never commit API keys to version control
Use environment variables or secure vaults
Rotate keys regularly

# Good: Use environment variables
export DOKPLOY_API_KEY="prod_dkp_live_abc123..."
curl -H "x-api-key: $DOKPLOY_API_KEY" ...

# Bad: Hardcoded in scripts
curl -H "x-api-key: prod_dkp_live_abc123..." ...

2. Use Descriptive Names

Name your API keys based on their purpose:

{
  "name": "GitHub Actions - Production Deployments",
  "prefix": "gh-prod"
}

3. Set Expiration Dates

For temporary access, set expiration dates:

{
  "name": "Temporary Migration Key",
  "expiresIn": 604800000  // 7 days in milliseconds
}

4. Implement Rate Limiting

Always enable rate limiting for production keys:

{
  "rateLimitEnabled": true,
  "rateLimitTimeWindow": 60000,
  "rateLimitMax": 100
}

5. Use Specific Keys for Different Environments

Create separate keys for development, staging, and production:

# Development
{
  "name": "Development Environment",
  "prefix": "dev"
}

# Production
{
  "name": "Production Environment",
  "prefix": "prod"
}

Authorization

API keys inherit the permissions of the user who created them. Authorization is based on:

Organization Membership

API keys are scoped to a specific organization. The key can only access resources within that organization.

User Roles

Dokploy has three user roles with different permissions:

Role	Permissions
Owner	Full access to all resources and settings
Admin	Manage resources, users, and settings (except billing)
Member	View and manage assigned resources

Protected Procedures

Some API procedures require specific roles:

adminProcedure: Requires Owner or Admin role
protectedProcedure: Requires any authenticated user
publicProcedure: No authentication required

Authentication Errors

401 Unauthorized

Missing or invalid API key:

{
  "error": {
    "message": "UNAUTHORIZED",
    "code": "UNAUTHORIZED",
    "data": {
      "httpStatus": 401
    }
  }
}

Common causes:

Missing x-api-key header
Invalid or expired API key
API key has been deleted

403 Forbidden

Authenticated but lacking permissions:

{
  "error": {
    "message": "You are not authorized to access this application",
    "code": "FORBIDDEN",
    "data": {
      "httpStatus": 403
    }
  }
}

Common causes:

Insufficient role (e.g., Member trying to access Admin endpoint)
Resource belongs to different organization
API key doesn’t have required permissions

Example: Complete Authentication Flow

Here’s a complete example of creating and using an API key:

# Step 1: Create API key (requires session authentication)
curl -X POST https://dokploy.example.com/api/trpc/user.createApiKey \
  -H "Content-Type: application/json" \
  -H "Cookie: better-auth.session_token=your-session" \
  -d '{
    "name": "Automation Script",
    "prefix": "auto",
    "metadata": {
      "organizationId": "org_abc123"
    },
    "rateLimitEnabled": true,
    "rateLimitTimeWindow": 60000,
    "rateLimitMax": 50
  }'

# Response:
# {
#   "result": {
#     "data": {
#       "key": "auto_dkp_live_xyz789..."
#     }
#   }
# }

# Step 2: Use the API key for subsequent requests
curl -X GET https://dokploy.example.com/api/trpc/project.all \
  -H "x-api-key: auto_dkp_live_xyz789..."

Next Steps

API Introduction

Learn about the API architecture and available routers

Projects API

Create and manage projects via API

Applications API

Deploy and manage applications programmatically

Error Handling

Handle API errors effectively

Overview

Applications

Databases

Projects & Deployments

Infrastructure

Configuration

​Authentication Methods

​API Key Authentication

​How It Works

​Creating an API Key

​Create API Key Endpoint

​Using API Keys

​Example: List All Projects

​Example: Create a New Application

​Example: Deploy an Application

​Managing API Keys

​List Your API Keys

​Delete an API Key

​Rate Limiting

​Rate Limit Configuration

​Example: API Key with Rate Limiting

​Security Best Practices

​1. Store Keys Securely

​2. Use Descriptive Names

​3. Set Expiration Dates

​4. Implement Rate Limiting

​5. Use Specific Keys for Different Environments

​Authorization

​Organization Membership

​User Roles

​Protected Procedures

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​Example: Complete Authentication Flow

​Next Steps

API Introduction

Projects API

Applications API

Error Handling

Authentication Methods

API Key Authentication

How It Works

Creating an API Key

Create API Key Endpoint

Using API Keys

Example: List All Projects

Example: Create a New Application

Example: Deploy an Application

Managing API Keys

List Your API Keys

Delete an API Key

Rate Limiting

Rate Limit Configuration

Example: API Key with Rate Limiting

Security Best Practices

1. Store Keys Securely

2. Use Descriptive Names

3. Set Expiration Dates

4. Implement Rate Limiting

5. Use Specific Keys for Different Environments

Authorization

Organization Membership

User Roles

Protected Procedures

Authentication Errors

401 Unauthorized

403 Forbidden

Example: Complete Authentication Flow

Next Steps