---
title: "Create an entry for your address"
url: https://docs.corefinity.com/api/reference/firewall/create-firewall-entry-for-my-ip
type: endpoint
last_updated: 2026-11-13
feature: firewall
related:
  - https://docs.corefinity.com/guides/sites/access-and-security/firewall.md
---
# Create an entry for your address

Adds the address this request came from, for SSH and for the website, at the level you choose: `me` (every environment you can reach), this `environment`, its `website` or your `company`. When the address can already connect, nothing is added and the answer says what allows it. When the level already holds the address for SSH only or for the website only, that entry is widened to both rather than a second one added, and it keeps its expiry unless the one you ask for is later: an entry with no expiry stays without one, so `expires_in_days` never shortens it. Read `entry.expires_at` in the answer for when the address stops being allowed.

```http
POST /api/firewall/my-ip
```

- Scope: `write`
- Two-factor: required on your account (all)
- Rate limit: 10 a minute; 30 a minute for each person; 120 a minute for each company
- Long-running: answers with an operation to poll
- Try it in the console: off. It has not been cleared for the console. Copy the request and run it yourself when you are sure.

## Body

- `comment` (string or null)
- `environment_id` (integer, required): The environment you want to reach.
- `expires_in_days` (integer or null): After how many days a new entry stops being allowed. Null, or left out, for no expiry. An entry the level already holds for the address is widened instead and keeps its own expiry when that is later, or when it has none: read `entry.expires_at` in the answer. After how many days the address stops being allowed. Null, or left out, for no expiry. One of `1`, `30`, `90`, `365`, `null`.
- `level` (string, required): Where to add the address: for yourself (`me`), for this environment, for its website or for your company. One of `me`, `environment`, `website`, `company`.

## Request

### curl

```bash
curl -X POST https://manage.corefinity.com/api/firewall/my-ip \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Home",
    "environment_id": 1311,
    "expires_in_days": 30,
    "level": "me"
  }'
```

### PHP

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

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->post('https://manage.corefinity.com/api/firewall/my-ip', [
        'comment' => 'Home',
        'environment_id' => 1311,
        'expires_in_days' => 30,
        'level' => 'me',
    ]);

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

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/firewall/my-ip', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    comment: 'Home',
    environment_id: 1311,
    expires_in_days: 30,
    level: 'me',
  }),
});

// 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/firewall/my-ip",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "comment": "Home",
        "environment_id": 1311,
        "expires_in_days": 30,
        "level": "me",
    },
)

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

## Responses

### 200 The address can already connect. Nothing was added.

```json
{
  "present": true,
  "via": [
    {
      "cidr": "198.51.100.0/24",
      "entry_id": 9003,
      "layer": "company",
      "owner": {
        "id": 1204,
        "name": "Harbour & Finch",
        "type": "company"
      },
      "subscription_id": null
    }
  ]
}
```

### 201 The address was added, or the entry the level already held for it was widened to SSH and the website. `entry` is the entry as it now stands, with the expiry it has. Follow `change_id` with `GET /firewall/changes/{change}`.

```json
{
  "change_id": 5309,
  "entry": {
    "added_by": {
      "name": "Eleanor Finch",
      "on_behalf_of": null,
      "support": false
    },
    "carried_from": null,
    "changed_at": "2026-11-06T09:16:40Z",
    "cidr": "198.51.100.24/32",
    "comment": "Home",
    "created_at": "2026-11-06T09:16:40Z",
    "decision_reason": null,
    "editable": true,
    "expires_at": "2026-11-05T09:16:40Z",
    "family": 4,
    "id": 9005,
    "layer": "user",
    "owner": {
      "id": 2041,
      "name": "Eleanor Finch",
      "type": "user"
    },
    "path": null,
    "request_reason": null,
    "scope": {
      "ssh": true,
      "web": true
    },
    "source": "one_click",
    "status": "active",
    "web_paused": false
  }
}
```

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

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

### 403 The token lacks the `write` scope (`scope_required`), your company requires two-factor authentication and you have not set it up (`two_factor_required`), or you can see the entry or preset but may not change it, as with one your agency holds (`firewall_not_editable`).

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

### 404 The id does not exist or is something you cannot reach (`not_found`; both answer the same body), or the firewall is not on for it (`feature_off`).

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

### 422 The request was refused. `reason` says why: `invalid_arguments` (`environment_id`, `level`, `expires_in_days` or `comment` is missing or wrong, or a field is not part of the request; `field` names it), `firewall_address_refused` (the address is in a private, reserved or provider range; the message names which), `firewall_cap_exceeded` (the list, or an environment it reaches, holds its limit of addresses), `firewall_scope_invalid` (an IPv6 address at a level that reaches only CoreStack Enterprise environments, which have SSH only) or `firewall_duplicate` (the address is already at that level, waiting for approval).

```json
{
  "code": "firewall_address_refused",
  "field": "address",
  "message": "That address is in a private range and cannot be allowed.",
  "reason": "firewall_address_refused"
}
```

### 429 Too many requests: the endpoint's request limit (`rate_limited`, with `Retry-After`), or the firewall's own budget of 30 changes a minute for you and 120 for your company, which the Control Panel and AI assistants spend too (`firewall_throttled`). The budget's answer names no wait: try again after a minute.

```json
{
  "code": "firewall_throttled",
  "field": null,
  "message": "Too many firewall changes. Wait a minute and try again.",
  "reason": "firewall_throttled"
}
```

## 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 | `firewall_not_editable` | You can see this entry but you cannot change it. |
| 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. |
| 404 | `not_found` | Not found. |
| 422 | `firewall_address_refused` | That address is in a private range and cannot be allowed. |
| 422 | `invalid_arguments` | The arguments do not match the tool's input schema, or the Control Panel refused a field. Fix the fields named in the answer and call again. |
| 429 | `firewall_throttled` | Too many firewall changes. Wait a minute and try again. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |

## The same task elsewhere

- Guide: [Firewall](https://docs.corefinity.com/guides/sites/access-and-security/firewall.md)
