API Authorization

Coolify uses Bearer tokens to authenticate API requests.

Tokens are scoped to a single team and carry specific permissions that control what data and actions are available.

Who this is for?

This guide is for people who:

• Want to automate infrastructure management through the Coolify API.
• Are building integrations that interact with Coolify programmatically.
• Need to set up authentication for the MCP Server or other API-based tools.

How It Works?

Every API request must include a Bearer token in the Authorization header.

Coolify validates the token, identifies the user and team, then checks whether the token's permissions allow the requested action.

All resources returned by the API are scoped to the team the token was created under.

If you work across multiple teams, you need a separate token for each one.

Example Data

1. Enable the API

DashboardAPI

You can enable or disable the API from the dashboard:

1. Go to Settings in the sidebar.
2. Click on Advanced.
3. Find the API Settings section and toggle API Access on.

TIP

Optionally, configure Allowed IPs to restrict API access to specific IP addresses.

Leave it empty or set to 0.0.0.0 to allow all IPs (not recommended for production usage)

If you already have a token with root permissions, you can enable or disable the API programmatically:

# Enable API
curl -X POST https://coolify.shadowarcanist.com/api/v1/enable \
  -H "Authorization: Bearer 67|abcthisisa123dummytoken"

# Disable API
curl -X POST https://coolify.shadowarcanist.com/api/v1/disable \
  -H "Authorization: Bearer 67|abcthisisa123dummytoken"

These endpoints require a token with root permissions.

2. Create an API Token

1. Go to Security in the sidebar.
2. Click on API Tokens.
3. Enter a name for your token.
4. Choose an expiration period — 7, 30, 60, 90, 1 year, or no expiration.
5. Select the permissions you need (see Permissions below).
6. Click Create button.

Your token will look like this:

67|abcthisisa123dummytoken

The number before the | is the token ID. Everything after is the secret — both parts are required for authentication.

3. Make API Requests

Include your token in the Authorization header of every request:

curl https://coolify.shadowarcanist.com/api/v1/teams \
  -H "Authorization: Bearer 67|abcthisisa123dummytoken"

Base URL

All API endpoints are available under:

https://coolify.shadowarcanist.com/api/v1

The only exceptions are /api/health and /api/feedback, which sit outside the /v1 prefix.

Permissions

Each token carries one or more permissions that control what it can access.

Select correct permissions when creating the token.

How Permissions Are Checked

• Each API endpoint requires a specific permission — read, write, or deploy.
• If your token doesn't have the required permission, the request returns 403 Forbidden with a list of the missing permissions.
• Tokens with root bypass all permission checks entirely.
• The read:sensitive permission controls whether sensitive fields (passwords, secrets, private keys, compose files) are included or redacted in responses.

Team Scoping

Every API token is bound to the team that was active when the token was created. The token can only access resources belonging to that team.

• Servers, projects, applications, databases, and services are all filtered by the token's team.
• If you don't see a resource in API responses, it likely belongs to a different team.
• To access resources across multiple teams, create a separate token while each team is active.

Rate Limiting

API requests are rate-limited to 200 requests per minute by default. This applies globally and can be configured via the API_RATE_LIMIT environment variable for Coolify.

When you exceed the rate limit, the API returns 429 Too Many Requests.

IP Allowlisting

You can restrict API access to specific IP addresses, so only trusted networks can reach your instance's API.

Configure Allowed IPs

1. Go to Settings in the sidebar.
2. Click on Advanced.
3. Find the Allowed IPs for API Access field.
4. Enter your allowed IPs as a comma-separated list.

# Single IPs
192.168.1.100,203.0.113.50

# CIDR notation
10.0.0.0/8,172.16.0.0/16

# Mixed
192.168.1.100,10.0.0.0/8,203.0.113.0/24

Both IPv4 and IPv6 addresses are supported, including CIDR ranges.

Behavior

Coolify automatically deduplicates entries — if a specific IP is already covered by a CIDR range in your list, the redundant entry is removed.

Security Considerations

• Token storage — Tokens are stored as SHA-256 hashes. Coolify cannot retrieve your token after creation — if you lose it, create a new one.
• Token expiration — Set an expiration period for tokens used in automated systems. Coolify sends an email warning before a token expires.
• IP allowlisting — Restrict API access to trusted IPs only. See IP Allowlisting above.
• Team isolation — Tokens only access resources within their team. A leaked token cannot access other teams' resources.
• Revocation — Delete a token from Security > API Tokens to immediately revoke access.

Troubleshooting