Skip to content
Merged

v4.7 #749

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
89 commits
Select commit Hold shift + click to select a range
0dc7a89
docs(log-drains): document Fluent Bit 5.1 upgrade and restrictions (#…
andrasbacsai Nov 9, 2026
c7beef6
docs(api): refresh OpenAPI reference for v4.7.1
ShadowArcanist Nov 9, 2026
a192cc6
docs(servers): document the server security page and SSH host key pin…
ShadowArcanist Nov 9, 2026
5677f65
docs(troubleshoot): add host key change and SSH session limit entries
ShadowArcanist Nov 9, 2026
9134fd5
docs(servers): update terminal access path and document session end
ShadowArcanist Nov 9, 2026
69a5d7a
docs(ssh-keys): document key rotation and stricter key validation
ShadowArcanist Nov 9, 2026
61bdc7f
docs(servers): document server delete for additional destinations and…
ShadowArcanist Nov 9, 2026
1362911
docs(servers): update server details, provider link labels and build …
ShadowArcanist Nov 9, 2026
24da5dc
docs(mcp): require the delete ability for delete actions
ShadowArcanist Nov 9, 2026
2d04a02
docs(mcp): document cancel_previous for the deploy tool
ShadowArcanist Nov 9, 2026
1cfaede
docs(mcp): add dns, integration token, secret manager, tunnel and git…
ShadowArcanist Nov 9, 2026
1c70837
docs(mcp): add image scanning tools
ShadowArcanist Nov 9, 2026
c6320d0
docs(security): document container image scanning
ShadowArcanist Nov 9, 2026
7730e5e
docs(api): document the delete permission and token access
ShadowArcanist Nov 9, 2026
827d6b9
docs(api): document the failed request limit
ShadowArcanist Nov 9, 2026
13e662e
docs(api): require an instance admin to disable the API
ShadowArcanist Nov 9, 2026
32ef4ed
docs(security): document api token access, edit, pause and roll
ShadowArcanist Nov 9, 2026
bcbd803
docs(team): document member access grants
ShadowArcanist Nov 9, 2026
d82ee16
docs(team): update member actions, confirmations and invite access
ShadowArcanist Nov 9, 2026
4d02fd2
docs(team): document audit anonymization of deleted users
ShadowArcanist Nov 9, 2026
14102b8
docs(team): document locked shared variable replacement
ShadowArcanist Nov 9, 2026
198a5f9
docs(instance-settings): document the email provider list and notific…
ShadowArcanist Nov 9, 2026
9d3a01f
docs(notifications): document automatically disabled channels
ShadowArcanist Nov 9, 2026
3e7e181
docs(notifications): document smtp servers and host checks for team e…
ShadowArcanist Nov 9, 2026
f0f033b
docs(notifications): document webhook url checks and delivery responses
ShadowArcanist Nov 9, 2026
8c6fcd8
docs(notifications): update event labels, throttling and new notifica…
ShadowArcanist Nov 9, 2026
3603553
docs(notifications): add new webhook events to the payload reference
ShadowArcanist Nov 9, 2026
2dc1c81
docs(upgrade): document update channels and update notifications
ShadowArcanist Nov 9, 2026
84b1be9
docs(install): document preview and nightly installs and fix the regi…
ShadowArcanist Nov 9, 2026
1b209ce
docs(instance): document ssh host key checking and api failed request…
ShadowArcanist Nov 9, 2026
9d0b252
docs(reverb): stop routing the reverb http api path
ShadowArcanist Nov 9, 2026
d0ceb12
docs(cloud): document data retention after a subscription ends
ShadowArcanist Nov 9, 2026
e475432
docs(sources): add Forgejo and Codeberg to the Gitea App
ShadowArcanist Nov 9, 2026
a23a6bb
docs(sources): add HTTPS credentials for custom Git hosts
ShadowArcanist Nov 9, 2026
2c1eead
docs(github): document GitHub deployments sync
ShadowArcanist Nov 9, 2026
c0d62c5
docs(sources): document SSH host key pinning
ShadowArcanist Nov 9, 2026
3e4f2e8
docs(applications): document webhook deployment cancel and network ho…
ShadowArcanist Nov 9, 2026
c9cd977
docs(applications): require write for preview changes and document ro…
ShadowArcanist Nov 9, 2026
ddf3c29
docs(applications): document skipped scheduled task runs and run in a…
ShadowArcanist Nov 9, 2026
a42b164
docs(applications): update operations overview for skipped tasks and …
ShadowArcanist Nov 9, 2026
8474b3f
docs(applications): document compose base directory, watch paths and …
ShadowArcanist Nov 9, 2026
1d1626c
docs(applications): document interactive and tty custom docker options
ShadowArcanist Nov 9, 2026
376502d
docs(applications): document compose defaults, exact multiline values…
ShadowArcanist Nov 9, 2026
5e87676
docs(proxy): move maintenance mode to the Maintenance Mode page
ShadowArcanist Nov 9, 2026
a1c162e
docs(proxy): document unused Traefik TLS certificates
ShadowArcanist Nov 9, 2026
7462ba2
docs(proxy): route only the Reverb /app/ path to Coolify
ShadowArcanist Nov 9, 2026
753eb17
docs(dns): document Cloudflare DNS mismatch and API record management
ShadowArcanist Nov 9, 2026
55b33f3
docs(security): document secret manager API and MCP access
ShadowArcanist Nov 9, 2026
e8bef45
docs(s3-storage): add SFTP, FTPS and WebDAV storages and the TLS skip…
ShadowArcanist Nov 9, 2026
c8147ae
docs(databases): move import backup to the backups page
ShadowArcanist Nov 9, 2026
2516c3e
docs(databases): update default images of new databases and add valkey
ShadowArcanist Nov 9, 2026
33e8ad6
docs(databases): update the sqlite user id note
ShadowArcanist Nov 9, 2026
32211c6
docs(automation): add run in a shell and automatic disable to schedul…
ShadowArcanist Nov 9, 2026
898434a
docs(automation): add cancel_previous, pr and docker_tag to deploy we…
ShadowArcanist Nov 9, 2026
50916ad
docs(persistent-storage): warn that a volume rename uses a new empty …
ShadowArcanist Nov 9, 2026
07e391a
docs(services): add Orbit and Hi.Events
ShadowArcanist Nov 9, 2026
86f3b01
docs(services): add PostgreSQL 12 to 16 upgrade steps for Outline
ShadowArcanist Nov 9, 2026
d544292
docs(services): add fix steps for existing template services
ShadowArcanist Nov 9, 2026
ca6bd2f
docs(services): point hidden Hoarder and OpenBlocks pages to replacem…
ShadowArcanist Nov 9, 2026
6cf794c
docs(services): document removed Compose services and Compose defaults
ShadowArcanist Nov 9, 2026
84384f8
docs(services): move service Import backup to the Backups page
ShadowArcanist Nov 9, 2026
44adadf
docs(tutorials): fix deploy token note and add delete to the root bypass
ShadowArcanist Nov 9, 2026
1a4c8ce
docs(automation): clear read for a deploy-only webhook token
ShadowArcanist Nov 9, 2026
9e939ac
docs(security): use the Allowed IPs label for API access
ShadowArcanist Nov 9, 2026
d6f0152
docs(tutorials): select the Redis image in the first database guide
ShadowArcanist Nov 9, 2026
8a71e18
docs(applications): note Forgejo support for manual Gitea webhooks
ShadowArcanist Nov 9, 2026
59e8161
fix(redirects): send service template variants to their base pages
ShadowArcanist Nov 9, 2026
c686369
docs(servers): add the image scanning option to the new server form
ShadowArcanist Nov 9, 2026
c69fba0
chore(ai): note service variant redirects and tab anchor checks
ShadowArcanist Nov 9, 2026
69fd458
docs(install): document the root account setup window
ShadowArcanist Nov 9, 2026
71c3375
docs(security): document the scanner memory limit and disk usage
ShadowArcanist Nov 9, 2026
c707d08
docs(upgrade): mention the nightly hint on the stable channel
ShadowArcanist Nov 9, 2026
94a0a55
docs(team): correct the user deletion rules and steps
ShadowArcanist Nov 9, 2026
f2e7922
docs(team): align member access levels and role permissions with core
ShadowArcanist Nov 9, 2026
71bb2d6
docs(team): fix the invite scope label and the owner removal note
ShadowArcanist Nov 9, 2026
8bf4415
docs(team): document the team two-factor requirement
ShadowArcanist Nov 9, 2026
4137237
docs(api): document all operation checks, write:sensitive and error m…
ShadowArcanist Nov 9, 2026
9134858
docs(api): use the /team endpoint in examples and clarify request checks
ShadowArcanist Nov 9, 2026
5f7a680
docs(security): update api token access, list and failed request details
ShadowArcanist Nov 9, 2026
1c76975
docs(security): cover mcp and scoped access in the security model
ShadowArcanist Nov 9, 2026
7fae0fb
docs(mcp): describe tool visibility per permission and token checks
ShadowArcanist Nov 9, 2026
679f01c
docs(servers): require the owner role for a server transfer
ShadowArcanist Nov 9, 2026
496883d
chore: merge main into next
ShadowArcanist Nov 9, 2026
96acafc
docs(log-drains): list every blocked Fluent Bit directive and section
ShadowArcanist Nov 9, 2026
2549547
docs(automation): send deploy webhooks with POST
ShadowArcanist Nov 9, 2026
a5c02f5
docs(instance-settings): fix the swapped anonymous telemetry values
ShadowArcanist Nov 9, 2026
38cb454
docs(applications): an enabled healthcheck replaces the Dockerfile HE…
ShadowArcanist Nov 9, 2026
4bb2245
docs(applications): max restart count defaults to no limit
ShadowArcanist Nov 9, 2026
38d3198
fix(proxy): update traefik version in the proxy updating page (#746)
RisDN Nov 9, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .ai/lessons.md
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
- In custom MDX components, use `fumadocs-core/link` instead of raw anchor elements so internal links include the configured `/docs` base path.
- The Coolify UI links each one-click service to `/docs/services/<template-key>`. A variant template (`<name>-with-*`) without its own page needs a redirect in `nginx/redirects.conf`.
- Headings inside `<Tabs>` are not in the prerendered HTML of `.output/public`, so an anchor check on the build output reports false "missing anchor" hits for them.
27,801 changes: 15,791 additions & 12,010 deletions config/openapi.json

Large diffs are not rendered by default.

27 changes: 15 additions & 12 deletions content/docs/api/authorization.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@ description: Authenticate Coolify API requests with a Bearer token and understan

# API Authorization

Coolify authenticates protected API requests with Bearer tokens. Each token belongs to the user and active team that created it and includes the permissions selected during creation.
Coolify authenticates protected API requests with Bearer tokens. Each token belongs to the user and active team that created it and includes the permissions and access selected for it.

## Before you make a request

Follow [API Tokens](/core/security/credentials/api-tokens) to:

- create a token for the correct active team
- choose permissions and an expiration period
- choose permissions, access, and an expiration period
- copy the token into the caller's secret store

Use a separate token for each integration and team. Do not place tokens in source code, query strings, or deployment logs.
Expand All @@ -31,7 +31,7 @@ export COOLIFY_TOKEN="<api-token>"

curl --fail-with-body \
--header "Authorization: Bearer $COOLIFY_TOKEN" \
"$COOLIFY_URL/api/v1/teams/current"
"$COOLIFY_URL/api/v1/team"
```

The header format is:
Expand All @@ -40,29 +40,32 @@ The header format is:
Authorization: Bearer <api-token>
```

The token includes an ID, a `|` separator, and the secret value. Send the complete value exactly as Coolify displayed it when the token was created.
The token includes an ID, a `|` separator, and the secret value. Send the complete value exactly as Coolify displayed it when the token was created or rolled.

A successful request returns the team bound to the token.
A successful request returns the team bound to the token. A token limited to selected projects, environments, or resources gets `403 Forbidden` from this team-level endpoint. Test it with `GET /api/v1/projects` instead.

---

## Authorization checks

A protected request passes through these checks:

1. The token exists, has not expired, and authenticates a user.
1. The token exists, has not expired, is not paused, and authenticates a user.
2. The user still belongs to the team recorded when the token was created.
3. On a self-hosted instance, [API Access](/api/ip-allowlist) is enabled and the caller matches the IP allowlist when one is set.
4. The token has the permission required by the endpoint, unless it has `root`.
5. A token using `write` or `root` still belongs to a team administrator or owner.
3. The token does not have more access than its owner currently has in that team.
4. On a self-hosted instance, [API Access](/api/ip-allowlist) is enabled and the caller matches the IP allowlist when one is set. The instance-administrator endpoints check only the IP allowlist.
5. A token limited to selected projects, environments, or resources calls an endpoint for projects and resources, not a team-level endpoint.
6. The token has the permission required by the endpoint, unless it has `root`.
7. The requested project, environment, or resource is inside the access of the token and its owner. Some endpoints also need the token owner to be a team administrator or owner. See [Permissions](/api/permissions#team-and-role-scope).

| Status | Typical meaning |
| :--- | :--- |
| `401` | Unauthenticated. The token is missing, invalid, expired, revoked, or no longer belongs to a current team member. |
| `403` | Forbidden. API access or the caller's IP is blocked, the token lacks the required permission, or the token owner lacks the required role. |
| `401` | Unauthenticated. The token is missing, invalid, expired, paused, revoked, or no longer belongs to a current team member. |
| `403` | Forbidden. API access or the caller's IP is blocked, the token lacks the required permission or access, or the token has more access than its owner. |
| `429` | Too many requests. The caller sent too many requests or too many failed requests. See [Rate Limits](/api/rate-limits). |

See [API errors](/api/errors) for other status codes and response-handling guidance.

---

Review [Permissions](/api/permissions) before choosing token abilities. Read the [API overview](/api/overview) for base URLs and the other API reference sections.
Review [Permissions](/api/permissions) before choosing token permissions and access. Read the [API overview](/api/overview) for base URLs and the other API reference sections.
53 changes: 38 additions & 15 deletions content/docs/api/errors.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -39,12 +39,12 @@ Do not parse the human-readable message to decide whether a request succeeded. U
| `200 OK` | The request succeeded. | Read the response body for the operation result. |
| `201 Created` | Coolify created the requested resource. | Store the returned identifier and verify the resource state when required. |
| `400 Bad Request` | The request or token is invalid for the operation. | Check the endpoint schema, parameters, and complete token value. |
| `401 Unauthenticated` | Coolify could not authenticate the request. | Replace a missing, invalid, expired, or revoked token. |
| `403 Forbidden` | The authenticated caller cannot perform the operation. | Check token permissions, team role, API access, and the source-IP allowlist. |
| `401 Unauthenticated` | Coolify could not authenticate the request. | Replace a missing, invalid, expired, or revoked token, or resume a paused token. |
| `403 Forbidden` | The authenticated caller cannot perform the operation. | Check token permissions and access, the owner's access, API access, and the source-IP allowlist. |
| `404 Not Found` | The route or requested resource is unavailable to the caller. | Check the URL, resource identifier, and token team. |
| `409 Conflict` | The requested change conflicts with existing state, such as an existing domain. | Read the response and resolve the conflicting state before retrying. |
| `422 Unprocessable Content` | One or more request fields failed validation. | Correct the fields listed in `errors`, then send a new request. |
| `429 Too Many Requests` | A request limit, deployment queue, or upstream provider rejected the request temporarily. | Follow `Retry-After` and the [rate-limit guidance](/api/rate-limits#handle-a-429-response). |
| `429 Too Many Requests` | A request limit, the failed request limit, a deployment queue, or an upstream provider rejected the request temporarily. | Follow `Retry-After` and the [rate-limit guidance](/api/rate-limits#handle-a-429-response). |

Each operation page under **Endpoints** lists its documented responses.

Expand All @@ -56,41 +56,64 @@ For `401 Unauthenticated`, confirm that:

- the header uses `Authorization: Bearer <api-token>`
- the complete token value, including the ID and `|` separator, is present
- the token has not expired or been revoked
- the token has not expired, been paused, or been revoked
- the token owner still belongs to the token's team

The `message` field shows the cause:

| Message | Cause |
| :--- | :--- |
| `Unauthenticated.` | The token is missing, invalid, expired, paused, or revoked. |
| `Invalid token.` | The token owner is no longer a member of the token's team. |

A password change revokes that user's issued API tokens. Create a replacement token when this happens.

For `403 Forbidden`, confirm that:

- the token has the endpoint's required `read`, `write`, or `deploy` permission
- the token owner still has an administrator or owner role when using `write` or `root`
- **API Access** is enabled on a self-hosted instance
- the caller matches **Allowed IPs for API Access** when an allowlist is configured

Token permissions cannot be changed after creation. Create a replacement token with the required permissions and revoke the previous token.
- the token has the endpoint's required `read`, `write`, `delete`, or `deploy` permission
- a token limited to selected projects, environments, or resources calls an endpoint for projects and resources, and the requested item is inside its access
- the token owner still has the access that the token uses
- the token owner has the role that the endpoint needs, for example team administrator or owner
- **API access** is enabled on a self-hosted instance
- the caller matches **Allowed IPs** when an allowlist is configured

The `message` field tells you which check failed:

| Message | Cause |
| :--- | :--- |
| `Missing required permissions: <permission>` | The token does not have the permission that the endpoint requires. For an [operation-specific check](/api/permissions#operation-specific-checks), Coolify adds the reason after the permission. |
| `This API token is limited to selected projects, environments, or resources, so it cannot use this endpoint.` | The endpoint is team-level, and the token has limited access. |
| `This API token has more access than you have in this team. Revoke it and create a new token.` | The token owner lost access that the token uses, or a selected project, environment, or resource of a member's token was deleted. |
| `API is disabled.` | **API access** is off on a self-hosted instance. |
| `You are not allowed to disable the API.`, `You are not allowed to enable the MCP server.`, `You are not allowed to disable the MCP server.` | The token is not a root-team token of an instance administrator. |
| `Instance email settings require a root-team API token.` | The token for `/settings/email` was not created in the root team. |
| `This action is unauthorized.` | `GET /cloud-tokens` needs a token owner who is a team administrator or owner. |
| `Only team admins and owners can view audit logs.` | `GET /audit-events` needs a token owner who is a team administrator or owner. |
| `You are not authorized to perform this action.` | The role or access of the token owner does not allow the operation, for example a member who manages cloud tokens. |

To fix the permissions or access of a token, [edit the token](/core/security/credentials/api-tokens#manage-a-token). Its value does not change.

### IP allowlist rejections

On a self-hosted instance, a request from an address outside **Allowed IPs for API Access** returns `403 Forbidden`:
On a self-hosted instance, a request from an address outside **Allowed IPs** returns `403 Forbidden`:

```json
{
"success": true,
"success": false,
"message": "You are not allowed to access the API."
}
```

Treat the HTTP `403` status as the failure signal even though this response contains `"success": true`. Add the caller's exact source IP address or network to the allowlist, then make the request again. Follow [Restrict API access by IP address](/api/ip-allowlist#restrict-api-access-by-ip-address) for supported values and configuration steps.
Treat the HTTP `403` status as the failure signal. Add the caller's exact source IP address or network to the allowlist, then make the request again. Follow [Restrict API access by IP address](/api/ip-allowlist#restrict-api-access-by-ip-address) for supported values and configuration steps.

---

## Missing or redacted data

A successful request can still omit expected resources or redact sensitive values.

- If a resource is missing, confirm that it belongs to the team recorded when the token was created. Create a separate token for another team.
- If passwords, private keys, environment values, logs, or Compose content are redacted, use a token with `read:sensitive` in addition to the endpoint's required permission.
- If a resource is missing, confirm that it belongs to the team recorded when the token was created and that it is inside the token's access. Create a separate token for another team.
- If passwords, private keys, environment values, logs, or Compose content are redacted, use a token with `read:sensitive` in addition to the endpoint's required permission. For most values, the token owner must also be a team administrator or owner. Locked environment variable values are never returned. See [Sensitive response data](/api/permissions#sensitive-response-data).

Read [Authorization](/api/authorization) for the complete request and access-check flow.

Expand Down
12 changes: 7 additions & 5 deletions content/docs/api/ip-allowlist.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,23 +12,25 @@ Self-hosted Coolify administrators can enable API access for the instance and re
Open **Settings > Advanced**. Under **API and MCP**, the page contains:

- **API access**, which allows or blocks authenticated REST API requests
- **Allowed API IPs**, which accepts exact IP addresses and networks in CIDR notation
- **Allowed IPs**, which accepts exact IP addresses and networks in CIDR notation

When **API access** is off, protected REST API requests return `403 Forbidden` even when the Bearer token is valid. Enable REST API access through the dashboard; `POST /api/v1/enable` has been removed.

MCP has its own **MCP server** switch and can remain enabled while REST API access is off. **Allowed API IPs** applies to both REST API and MCP requests, including API/MCP control endpoints. See [Set up MCP](/mcp/setup).
Through the API, only an instance administrator can disable the API or enable and disable the MCP server. `POST /api/v1/disable`, `POST /api/v1/mcp/enable`, and `POST /api/v1/mcp/disable` require a `write` or `root` token created in the root team by an administrator or owner of that team. Other tokens receive `403 Forbidden`.

MCP has its own **MCP server** switch and can remain enabled while REST API access is off. **Allowed IPs** applies to both REST API and MCP requests, including API/MCP control endpoints. See [Set up MCP](/mcp/setup).

---

## Restrict API access by IP address

**Allowed API IPs** is an instance-wide allowlist. When the field contains one or more entries, Coolify rejects a request unless its source IP matches an exact address or one of the listed networks.
**Allowed IPs** is an instance-wide allowlist. When the field contains one or more entries, Coolify rejects a request unless its source IP matches an exact address or one of the listed networks.

Before changing the allowlist, identify the source address that Coolify receives from each API client. If a client connects through NAT, add its public outbound IP address rather than its private address.

1. Open **Settings > Advanced**.
2. Under **API and MCP**, set **API access** to **Enabled**.
3. Enter exact IPv4 or IPv6 addresses, or networks in CIDR notation, in **Allowed API IPs**.
3. Enter exact IPv4 or IPv6 addresses, or networks in CIDR notation, in **Allowed IPs**.
4. Separate multiple entries with commas.
5. Select **Save changes**.

Expand Down Expand Up @@ -68,7 +70,7 @@ docker network inspect coolify \
--format '{{range .IPAM.Config}}{{println .Subnet}}{{end}}'
```

Add every IPv4 and IPv6 subnet returned by the command to **Allowed API IPs**, separated by commas.
Add every IPv4 and IPv6 subnet returned by the command to **Allowed IPs**, separated by commas.

<Callout type="warning" title="Allow the network only when required">
Allowing an entire Docker subnet permits every container on that subnet to pass the IP check. API tokens and their permissions still apply, but you should connect only trusted containers to the `coolify` network.
Expand Down
2 changes: 1 addition & 1 deletion content/docs/api/making-requests.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ curl --fail-with-body \
--request GET \
--header "Authorization: Bearer $COOLIFY_TOKEN" \
--header "Accept: application/json" \
"$COOLIFY_URL/api/v1/teams/current"
"$COOLIFY_URL/api/v1/team"
```

Use `Content-Type: application/json` when the request includes a JSON body:
Expand Down
2 changes: 1 addition & 1 deletion content/docs/api/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ On a self-hosted instance, an administrator must also enable API access. Use [IP

- [Making Requests](/api/making-requests) explains URLs, methods, headers, parameters, bodies, and responses.
- [Authorization](/api/authorization) explains Bearer tokens and access checks.
- [Permissions](/api/permissions) covers token abilities, team scope, roles, and sensitive data.
- [Permissions](/api/permissions) covers token permissions, access, team scope, roles, and sensitive data.
- [IP Allowlist](/api/ip-allowlist) covers self-hosted API access and source-IP restrictions.
- [Rate Limits](/api/rate-limits) documents request limits, response headers, and retries.
- [Errors](/api/errors) explains status codes and common failure responses.
Expand Down
Loading
Loading