---
title: "Turn external database access on"
url: https://docs.corefinity.com/api/reference/database/enable-site-external-database
type: endpoint
last_updated: 2026-11-13
feature: database
related:
  - https://docs.corefinity.com/guides/sites/database/database-users.md
  - https://docs.corefinity.com/mcp/tools/corestack_external_db_enable.md
---
# Turn external database access on

Gives the environment a fixed public address and a host name that only the addresses you list can reach, as a
paid add-on charged monthly from when access is on. It needs a person who can change the site's billing, and
`confirm_cost: true` once the charge in `external.price` of the database details is agreed. The first turn-on
is applied in the environment's nightly maintenance window and answers `operation: null`; later ones start at
once.

```http
POST /api/corestack/sites/{site}/external-db/enable
```

- Scope: `write`
- Two-factor: required on your account (all)
- Rate limit: 20 a minute
- Long-running: answers with an operation to poll
- Try it in the console: off. It can add to your bill. Copy the request and run it yourself when you are sure.

## Path parameters

- `site` (integer, required): The id of a site row. A website's production site and each of its environments has its own id. Digits only.

## Body

- `confirm_cost` (boolean, required): True once you have agreed to the monthly charge.
- `sources` (array of objects, required)
  - `cidr` (string, required): A public IPv4 address, or a block from `/32` to `/28` written from its first address. Private, shared, loopback, link-local, multicast, reserved and documentation ranges are refused.
  - `label` (string or null)

## Request

### curl

```bash
curl -X POST https://manage.corefinity.com/api/corestack/sites/1042/external-db/enable \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "confirm_cost": true,
    "sources": [
      {
        "cidr": "198.51.100.64/29",
        "label": "Order system"
      }
    ]
  }'
```

### PHP

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->post('https://manage.corefinity.com/api/corestack/sites/1042/external-db/enable', [
        'confirm_cost' => true,
        'sources' => [
            [
                'cidr' => '198.51.100.64/29',
                'label' => 'Order system',
            ],
        ],
    ]);

$data = $response->json();
```

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/external-db/enable', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    confirm_cost: true,
    sources: [
      {
        cidr: '198.51.100.64/29',
        label: 'Order system',
      },
    ],
  }),
});

// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);
```

### Python

```python
import os
import requests

res = requests.post(
    "https://manage.corefinity.com/api/corestack/sites/1042/external-db/enable",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "confirm_cost": True,
        "sources": [
            {
                "cidr": "198.51.100.64/29",
                "label": "Order system",
            },
        ],
    },
)

data = res.json() if res.content else None
```

## Responses

### 202 Access is being turned on (`operation` to follow), or, the first time, is queued for the maintenance window (`operation: null`, with `external` as it now reads).

```json
{
  "external": {
    "address": null,
    "available": true,
    "database": "application",
    "enabled_at": null,
    "enabled_by": null,
    "host": null,
    "moved_at": null,
    "operation": null,
    "port": 3306,
    "price": {
      "amount": "15.00",
      "billed_on": "corestack",
      "currency": "GBP",
      "label": "Dedicated IP address",
      "period": "month"
    },
    "sanitised": false,
    "sources": [
      {
        "added_at": null,
        "added_by": null,
        "cidr": "198.51.100.64/29",
        "label": "Order system",
        "pending": true
      }
    ],
    "sources_cap": 10,
    "status": "tonight",
    "tls": "optional",
    "window_date": "2026-11-04"
  },
  "operation": null
}
```

### 401 No token, or a token that is not valid.

```json
{
  "message": "Unauthenticated."
}
```

### 403 The token lacks the scope (`scope_required`), your company requires two-factor authentication and you have not set it up, your account has no company that can use Managed Clusters (`company_not_enabled`), or you cannot change the site's billing (`billing_forbidden`): an agency that manages a site it does not pay for asks the site's owner.

```json
{
  "code": "billing_forbidden",
  "message": "Billing for this site is Harbour & Finch's.",
  "reason": "billing_forbidden"
}
```

### 404 The id does not exist or is something you cannot see, or the feature is not on for your company (`feature_off`).

```json
{
  "code": "feature_off",
  "message": "Not found.",
  "reason": "feature_off"
}
```

### 409 Access cannot be turned on now. `reason` says why: `external_db_already_on`, `external_db_failed` (the last change did not finish: contact support), `busy` (a change to external access or to the site is running), `external_db_price_changed`, `deleted`, `provisioning`, `removed` or `managed_elsewhere`. A first turn-on, which waits for the maintenance window, is also refused while another change is already queued for that window (`change_pending`) or while queuing for the window is not available (`restart_batches_off`). On a site that is a demo, `demo_keep_required` answers with `keep_url` and the `change`: keep the site first.

```json
{
  "code": "busy",
  "message": "A change to external access is already in progress on this environment.",
  "reason": "busy"
}
```

### 422 A field is missing or wrong (`invalid`, with `field` and `errors`): `confirm_cost` is not `true`, or an address is refused. Or access is not available on this environment yet (`external_db_not_available`), or the add-on has no published price in your contract's currency (`currency_unpublished`).

```json
{
  "code": "invalid",
  "errors": {
    "confirm_cost": [
      "Confirm the monthly charge to turn external access on."
    ]
  },
  "field": "confirm_cost",
  "message": "Confirm the monthly charge to turn external access on.",
  "reason": "invalid"
}
```

### 429 Too many requests (`rate_limited`). Wait for the number of seconds in `Retry-After`, which `retry_after_seconds` repeats.

```json
{
  "code": "rate_limited",
  "message": "Too many requests. Try again in 60 seconds.",
  "reason": "rate_limited",
  "retry_after_seconds": 60
}
```

### 502 The environment's settings could not be read (`upstream_unavailable`). Nothing was changed; try again.

```json
{
  "code": "upstream_unavailable",
  "message": "The environment's settings could not be read. Try again in a moment.",
  "reason": "upstream_unavailable"
}
```

## If it is refused

| Status | Reason | What to do |
|---|---|---|
| 401 |  | Send a valid token as `Authorization: Bearer <token>`. |
| 403 | `billing_forbidden` | Billing is for the organisation's owner and billing contacts. Ask one of them to do this. |
| 403 | `company_unavailable` | Your company is unavailable. |
| 403 | `scope_required` | Use a token with the scope named in `scope`. |
| 403 | `two_factor_required` | Turn on two-factor on your account, then send again. |
| 404 | `feature_off` | This feature is not on for your organisation yet. |
| 409 | `busy` | Another operation is running on the site. Wait for it to finish. |
| 409 | `change_pending` | A change is already queued for tonight. Apply it now or cancel it first. |
| 409 | `demo_keep_required` | Creating CoreStack sites needs the demo to be kept first. Keep your demo, then try again. |
| 409 | `external_db_already_on` | External access is already on. Nothing to do. |
| 409 | `external_db_failed` | External access could not be turned on. Contact support so it can be finished or undone. |
| 409 | `restart_batches_off` | Changes cannot be queued for the maintenance window at the moment. Apply the change now instead. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 422 | `external_db_not_available` | External access is not available on the environment yet. Ask support. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |
| 502 | `upstream_unavailable` | A service the action depends on did not answer. Try again later. |

## The same task elsewhere

- Guide: [Database users](https://docs.corefinity.com/guides/sites/database/database-users.md)
- MCP tool: [`corestack_external_db_enable`](https://docs.corefinity.com/mcp/tools/corestack_external_db_enable.md)
