Skip to main content

Documentation Index

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

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

All Dokploy API requests require authentication. The recommended approach for programmatic and CI/CD access is an API key, passed via the x-api-key HTTP header on every request. Browser-based access to the dashboard uses session cookies managed automatically by Dokploy’s auth layer (powered by better-auth). This page covers everything you need to know about generating, using, and revoking API keys.

​
Generating an API Key

1

Log in to your Dokploy dashboard

Open your Dokploy instance in a browser and sign in with your account credentials.
2

Navigate to API Keys

Go to Settings → Profile → API Keys in the sidebar.
3

Create a new key

Click Generate New API Key, give it a descriptive name (for example, CI/CD pipeline or Monitoring agent), and configure any optional expiry or rate-limit settings.
4

Copy the key immediately

The full key value is only shown once at creation time. Copy it now and store it in a secrets manager or environment variable. You will not be able to retrieve it again from the dashboard.

​
Creating an API Key via the API

You can also create API keys programmatically using an existing authenticated session or API key. This is useful for bootstrapping CI environments or creating scoped keys on the fly. 
curl -X POST 'https://your-instance.com/api/user.createApiKey' \
  -H 'x-api-key: EXISTING_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "CI/CD pipeline key",
    "metadata": {
      "organizationId": "org_your_org_id"
    }
  }'
The metadata.organizationId field is required — the key is scoped to that organization. You must be a member of the organization you specify. You may also pass optional fields to control expiry and rate limiting:
​
name
string
required
A human-readable label for the key. Used to identify the key in the dashboard and audit logs.
​
prefix
string
Optional short string prepended to the generated key value (e.g. ci_). Useful for quickly identifying the key source.
​
expiresIn
number
Time-to-live in seconds. Omit for a non-expiring key.
​
metadata.organizationId
string
required
The organization the key should be scoped to. The authenticated user must be a member.
​
rateLimitEnabled
boolean
Enable per-key rate limiting.
​
rateLimitTimeWindow
number
Rate limit window duration in milliseconds.
​
rateLimitMax
number
Maximum number of requests allowed within the time window.
​
remaining
number
Total number of requests this key is allowed to make before it is exhausted. Leave unset for unlimited usage.

​
Using an API Key

Pass the key in the x-api-key header on every request: 
curl -X GET 'https://your-instance.com/api/project.all' \
  -H 'x-api-key: dp_your_api_key_here'

curl -X POST 'https://your-instance.com/api/application.deploy' \
  -H 'x-api-key: dp_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"applicationId": "app_abc123"}'
The header name is x-api-key (lowercase). Using Authorization: Bearer ... is not supported for API key authentication in Dokploy.

​
API Key Response Fields

When you create an API key (via the dashboard or the user.createApiKey endpoint), the response includes:
​
key
string
The raw API key value. This is the only time the full key is returned. Store it immediately.
​
id
string
Unique identifier for the key record. Use this id when deleting the key.
​
name
string
The human-readable name you assigned when creating the key.
​
createdAt
string
ISO 8601 timestamp of when the key was created (e.g. 2024-03-15T10:30:00.000Z).
​
expiresAt
string
ISO 8601 timestamp of when the key expires, or null if the key does not expire.
​
remaining
number
Number of requests remaining, or null if usage is unlimited.

​
Looking Up a User by Token

The user.getUserByToken endpoint lets you verify a token and retrieve the associated user record. This is a public procedure — it does not require an existing authenticated session: 
curl -X GET 'https://your-instance.com/api/user.getUserByToken?input=\{"token":"dp_your_api_key_here"\}'
This is useful for validating a key before storing it or for service-to-service identity checks.

​
Listing API Keys

Navigate to Settings → Profile → API Keys in the dashboard to see all keys associated with your account, including their names, creation dates, and expiry status. Listing keys via the API is not currently exposed as a dedicated endpoint — manage them through the dashboard UI.

​
Deleting an API Key

Delete a key by its id using the user.deleteApiKey mutation. You can only delete your own keys. 
curl -X POST 'https://your-instance.com/api/user.deleteApiKey' \
  -H 'x-api-key: YOUR_ACTIVE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"apiKeyId": "key_id_to_delete"}'
​
apiKeyId
string
required
The id of the API key to delete. Must belong to the authenticated user.
Deleting a key takes effect immediately. Any in-flight request that arrives after deletion will receive a 401 UNAUTHORIZED response. There is no grace period.

​
Session Authentication

For browser-based interactions, Dokploy uses session cookies issued by better-auth. When you log in through the dashboard, a secure HTTP-only session cookie is set automatically and included in subsequent requests by the browser. Session authentication is handled transparently by the Dokploy UI — you do not need to manage cookies manually for normal dashboard use. For programmatic access (scripts, CI, external services), always use an API key instead.

​
Generating a Token (Legacy)

The user.generateToken procedure exists for internal use and returns a placeholder token string. It is not intended for external API consumers — use user.createApiKey instead for all programmatic authentication needs.

​
Security Best Practices

Never commit API keys to source code or version control. Store keys in environment variables, a secrets manager (such as HashiCorp Vault, AWS Secrets Manager, or GitHub Actions Secrets), or an encrypted .env file that is excluded from your repository via .gitignore.
Follow these practices to keep your Dokploy instance secure:
  • Use descriptive names — label each key with its purpose and owner (e.g. github-actions-deploy, monitoring-agent) so you can audit and revoke individual keys without disrupting others.
  • Set expiry dates — short-lived keys reduce the blast radius of a compromise. Use expiresIn to enforce rotation.
  • Apply rate limits — for keys used in automated pipelines, enable rateLimitEnabled and set appropriate rateLimitMax and rateLimitTimeWindow values to prevent runaway processes from overloading your instance.
  • Rotate keys regularly — delete old keys and create fresh ones on a schedule (e.g. quarterly) or after any suspected exposure.
  • Use the minimum required scope — Dokploy keys inherit the role of the creating user within the specified organization. Create dedicated service accounts with the member role for automation tasks that do not require admin privileges.
  • Audit key usage — review the Dokploy audit log (available under Settings → Audit Logs on Enterprise plans) to detect unexpected API activity.

Build docs developers (and LLMs) love

Get started for freeTalk to us