---
title: "Replace a site's HTTP authentication"
url: https://docs.corefinity.com/api/reference/access/replace-site-http-auth
type: endpoint
last_updated: 2026-11-13
feature: http-auth
related:
  - https://docs.corefinity.com/guides/sites/access-and-security/password-protection.md
  - https://docs.corefinity.com/mcp/tools/corestack_http_auth_update.md
---
# Replace a site's HTTP authentication

Replaces the whole set of rules and users, so start from the last read and keep the `id` of every rule and
user you want to keep. The passwords this save set or generated are answered once, in `credentials`.

```http
PUT /api/corestack/sites/{site}/http-auth
```

- Scope: `write`
- Also needs `exec` when A user in the body asks for a generated password (`generate` is true)
- 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 overwrites data that cannot be brought back. 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

- `enabled` (boolean, required): Whether the whole environment asks for a login. True needs a whole-environment rule (`path_prefix` null) with at least one user, and that rule's own `enabled` must say the same.
- `rules` (array of objects, required)
  - `enabled` (boolean, required)
  - `id` (integer or null): A saved rule's id, to keep it. Leave it out, or send null, for a new rule.
  - `path_prefix` (string or null, required): Null for the whole environment. Otherwise a path that starts with `/` and contains only letters, digits, `-`, `_`, `.` and `/`.
  - `users` (array of objects, required)
    - `generate` (boolean): Ask the Control Panel to generate the password. A new user needs `password` or `generate`, never both; a saved user sent with neither keeps its password. Defaults to `false`.
    - `id` (integer or null): A saved user's id, to keep it. Leave it out, or send null, for a new user.
    - `password` (string or null): A password you choose: at least 12 characters and at most 72 bytes as UTF-8 (so fewer than 72 characters when it has characters outside ASCII), with at least one letter and one digit and no control characters. It cannot be the username, the site's main domain or its platform address.
    - `username` (string, required): Lower-case letters, digits, dots, dashes and underscores, 3 to 32 characters. The first and the last character are a letter or a digit.
- `version` (integer, required): The `version` of the last read.

## Request

### curl

```bash
curl -X PUT https://manage.corefinity.com/api/corestack/sites/1042/http-auth \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "rules": [
      {
        "enabled": true,
        "path_prefix": "/wp-admin/",
        "users": [
          {
            "password": "Example-editor-2026",
            "username": "editor"
          }
        ]
      }
    ],
    "version": 0
  }'
```

### PHP

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

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->put('https://manage.corefinity.com/api/corestack/sites/1042/http-auth', [
        'enabled' => false,
        'rules' => [
            [
                'enabled' => true,
                'path_prefix' => '/wp-admin/',
                'users' => [
                    [
                        'password' => 'Example-editor-2026',
                        'username' => 'editor',
                    ],
                ],
            ],
        ],
        'version' => 0,
    ]);

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

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/sites/1042/http-auth', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    enabled: false,
    rules: [
      {
        enabled: true,
        path_prefix: '/wp-admin/',
        users: [
          {
            password: 'Example-editor-2026',
            username: 'editor',
          },
        ],
      },
    ],
    version: 0,
  }),
});

// 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.put(
    "https://manage.corefinity.com/api/corestack/sites/1042/http-auth",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "enabled": False,
        "rules": [
            {
                "enabled": True,
                "path_prefix": "/wp-admin/",
                "users": [
                    {
                        "password": "Example-editor-2026",
                        "username": "editor",
                    },
                ],
            },
        ],
        "version": 0,
    },
)

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

## Responses

### 200 The set sent is the set the site already has. Nothing was started.

```json
{
  "credentials": [],
  "http_auth": {
    "apply": {
      "applied_at": null,
      "error": null,
      "operation": null,
      "state": "applied",
      "state_label": "Applied"
    },
    "bypass_corefinity": 1,
    "bypass_ips": [],
    "default_for_role": false,
    "enabled": false,
    "limits": {
      "prefix_max": 200,
      "rules_max": 20,
      "users_per_rule_max": 10
    },
    "note": "Passwords are stored encrypted and shown only when you reveal them; every reveal is recorded.",
    "rules": [],
    "version": 0
  },
  "operation": null
}
```

### 201 The set was saved and is being applied. Follow `operation.id` until it completes. `credentials` lists the passwords this save set or generated; the answer is sent with `Cache-Control: no-store, private`.

```json
{
  "credentials": [
    {
      "password": "Example-editor-2026",
      "revealed_at": "2026-11-06T15:00:00Z",
      "rule_id": 52,
      "user_id": 74,
      "username": "editor"
    }
  ],
  "http_auth": {
    "apply": {
      "applied_at": null,
      "detail": {
        "credentials": "pending"
      },
      "error": null,
      "operation": {
        "id": 431,
        "scope": "site",
        "status": "executing",
        "status_label": "Applying",
        "summary": "HTTP authentication: 1 rule, 1 user",
        "to_version": null,
        "type": "http_auth_change",
        "type_label": "HTTP authentication"
      },
      "state": "applying",
      "state_label": "Applying"
    },
    "bypass_corefinity": 1,
    "bypass_ips": [],
    "default_for_role": false,
    "enabled": false,
    "limits": {
      "prefix_max": 200,
      "rules_max": 20,
      "users_per_rule_max": 10
    },
    "note": "Passwords are stored encrypted and shown only when you reveal them; every reveal is recorded.",
    "rules": [
      {
        "enabled": true,
        "id": 52,
        "path_prefix": "/wp-admin/",
        "sort": 0,
        "users": [
          {
            "created_at": "2026-11-06T15:00:00Z",
            "id": 74,
            "password_set": true,
            "revealed_at": null,
            "username": "editor"
          }
        ]
      }
    ],
    "version": 1
  },
  "operation": {
    "completed_at": null,
    "created_at": "2026-11-06T15:00:00Z",
    "error": null,
    "id": 431,
    "scope": "site",
    "status": "executing",
    "status_label": "Applying",
    "steps": [
      {
        "key": "saved",
        "label": "Saved",
        "state": "done"
      },
      {
        "key": "credentials",
        "label": "Password live",
        "state": "current"
      }
    ],
    "type": "http_auth_change",
    "type_label": "HTTP authentication"
  }
}
```

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

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

### 403 The token lacks the scope (`scope_required`, with the `scope` to use), your company requires two-factor authentication and you have not set it up, or your account has no company that can use Managed Clusters, for example because the company was closed (`company_unavailable` or `company_not_enabled`, whichever the route checks first). For Managed Clusters routes; any other route uses `ForbiddenScopeOrTwoFactor`.

```json
{
  "code": "company_unavailable",
  "message": "Your company is unavailable.",
  "reason": "company_unavailable"
}
```

### 404 The site does not exist or is not yours to change, a rule or user `id` in the body is not one of this site's, or HTTP authentication saves are not on for your company (`feature_off`).

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

### 409 The save was refused because of the site's state. `reason` says why: `stale`, `busy`, `cluster_paused` (Corefinity has paused changes for planned maintenance: the message says until when, if that is known), `deleted`, `provisioning`, `removed`, `legacy_adopt_pending`, `legacy_domain_attached` or `managed_elsewhere`.

```json
{
  "code": "busy",
  "message": "Another change to this site is in progress. Wait for it to finish.",
  "reason": "busy"
}
```

### 422 A field is missing, wrong or not one the save takes. Rules and users are named by position, such as `rules.0.users.1.username`.

```json
{
  "code": "invalid",
  "errors": {
    "enabled": [
      "Add at least one user for the whole-environment rule"
    ]
  },
  "field": "enabled",
  "message": "Add at least one user for the whole-environment rule",
  "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 platform gave no answer while the save read the site's files, the platform did not save the change, or the Control Panel may not write this site's files. Nothing was changed. When the platform is at fault, try again shortly. The answer is a sentence only, with no `reason`.

```json
{
  "message": "The platform returned an error (HTTP 503). Try again shortly."
}
```

## If it is refused

| Status | Reason | What to do |
|---|---|---|
| 401 |  | Send a valid token as `Authorization: Bearer <token>`. |
| 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 | `cluster_paused` | Changes on this site are paused for planned maintenance; please try again later. |
| 409 | `deleted` | The site, environment or copy has been deleted, or is being deleted. Nothing can be changed on it. Restore a deleted site first if it can still be restored. |
| 409 | `legacy_adopt_pending` | HTTP authentication is being prepared for the site and is not available yet. Try again later. |
| 409 | `managed_elsewhere` | This site is read-only here. Change it in the control panel that manages it. |
| 409 | `stale` | What you read has changed since you read it. Read it again, then send the change with its new version or quote. |
| 422 | `invalid` | Fix the field named in `field`; `errors` says why. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |
| 502 |  | Read the message; it says what happened. |

## The same task elsewhere

- Guide: [Password protection](https://docs.corefinity.com/guides/sites/access-and-security/password-protection.md)
- MCP tool: [`corestack_http_auth_update`](https://docs.corefinity.com/mcp/tools/corestack_http_auth_update.md)
