> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitelshield.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference and authentication

> Authenticate to the Orbitel Shield REST API with scoped bearer keys, understand account boundaries and rate limits, and find resource endpoints.

The Orbitel Shield REST API provides your scripts and dashboards with the same account-scoped data as the panel. Send requests over HTTPS to read services, invoices, protection, analytics, and tickets, or use write scopes to change protection and support tickets.

## Base URL

```text theme={null}
https://portal.orbitelshield.com/api/v1/public
```

Paths in this reference are relative to this base URL. Request examples use the complete URL.

| Convention | Format |
| - | - |
| Account boundary | Every request is scoped to the account owning the API key |
| Responses | JSON; the ticket attachment endpoint downloads an attachment |
| Money | Integer amounts in cents |
| Timestamps | ISO 8601 in UTC |
| IDs | 26-character strings |
| Request bodies | Send JSON with `Content-Type: application/json` |

## Authentication

Create a key under **API keys** in the panel. Send it as a bearer token on every request.

```bash theme={null}
export ORBITEL_API_KEY="<your-api-key>"

curl "https://portal.orbitelshield.com/api/v1/public/key" \
  -H "Authorization: Bearer $ORBITEL_API_KEY"
```

Replace the placeholder with your key privately. Do not commit keys to source control or include them in logs, support tickets, screenshots, or documentation.

> [!WARNING]
>
> Keys work only under `/api/v1/public`. Panel pages, account pages, billing actions, and the admin area do not accept them. Conversely, the public API never accepts a signed-in browser session in place of a key. Public invoice read endpoints remain available with the appropriate scope.

### Key controls

* Limit a key to a list of allowed IP addresses if needed.
* Set an expiry to restrict its lifetime.
* Revoke a key to invalidate it on the next request.
* Grant only the scopes needed by the integration.

## Scopes

| Scope | Allows | Reference |
| - | - | - |
| Any scope | Inspect the key making the request | [Check a key](#check-a-key) |
| `services:read` | Read services, limits, status, and due dates | [Services and invoices](https://docs.orbitelshield.com/api-reference/services-invoices.md) |
| `invoices:read` | Read invoices, lines, tax, and payments | [Services and invoices](https://docs.orbitelshield.com/api-reference/services-invoices.md) |
| `protection:read` | Read prefixes, tunnels, traffic, and attacks | [Protection reads](https://docs.orbitelshield.com/api-reference/protection.md) |
| `protection:write` | Sync the network and change prefixes or tunnels | [Protection changes](https://docs.orbitelshield.com/api-reference/protection-changes.md) |
| `tickets:read` | Read tickets, messages, departments, services, and attachments | [Tickets](https://docs.orbitelshield.com/api-reference/tickets.md) |
| `tickets:write` | Open, reply to, and close tickets | [Tickets](https://docs.orbitelshield.com/api-reference/tickets.md) |

Do not assume a write scope also grants the corresponding read scope. Include the scopes needed for each endpoint your integration calls.

## Check a key

### `GET /key`

Works with any scope. Use this endpoint to check that a key is valid and inspect its name, prefix, scopes, and expiry.

```bash theme={null}
curl "https://portal.orbitelshield.com/api/v1/public/key" \
  -H "Authorization: Bearer $ORBITEL_API_KEY"
```

This returns information about the key that authenticated the request, not another key identified by an ID. The supplied specification does not define its exact JSON field names or response envelope.

## Rate limits

Each key allows **120 requests per minute**, of which **30 may change something**. The write allowance is part of the total, not an additional 30 requests.

Repeated bad keys from one IP address are blocked for **10 minutes**. Correct authentication problems rather than repeatedly submitting an invalid key.

When a request returns `429 rate_limited`, wait for the number of seconds specified in the `Retry-After` response header before trying again. See [errors](https://docs.orbitelshield.com/api-reference/errors.md).

## Resource reference

> [card] [Services and invoices](https://docs.orbitelshield.com/api-reference/services-invoices.md)
>
> Read service plans and status, then inspect invoice totals, lines, tax, and payments.

> [card] [Protection reads](https://docs.orbitelshield.com/api-reference/protection.md)
>
> Inspect prefixes and tunnels, query live traffic windows, and retrieve attack history.

> [card] [Protection changes](https://docs.orbitelshield.com/api-reference/protection-changes.md)
>
> Add or remove prefixes, create GRE tunnels, update delivery, and re-sync the network.

> [card] [Support tickets](https://docs.orbitelshield.com/api-reference/tickets.md)
>
> Read messages and attachments, open requests, reply, and close tickets.

> [card] [Errors](https://docs.orbitelshield.com/api-reference/errors.md)
>
> Handle authentication, scope, IP allowlist, validation, and rate-limit failures.

> [card] [Webhook signatures](https://docs.orbitelshield.com/api-reference/webhooks.md)
>
> Verify signed attack alerts using the raw body, timestamp, and channel signing secret.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.