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

# Authentication

> Create an API key, choose what it may call, and send it with every request.

Send your API key in the `Authorization` header of every request:

```bash theme={null}
curl --request GET \
  --url https://data-api.orbbit.co/v1/commodities \
  --header 'authorization: Bearer orbbit_data_YOUR_KEY'
```

A key is the text `orbbit_data_` followed by 64 letters and digits. Keep it secret: anyone holding it can call the API as you.

An agent with its own crypto wallet can instead call without a key and pay per call in USDC. See [Pay With x402](https://data-docs.orbbit.co/for-agents/x402.md).

## Your Default key

Every new account comes with one key already made, named **Default**. It can call every endpoint, including ones added later, and may spend up to \$5 a month. To copy it, open **API Keys**, find **Default**, and click **Reveal Secret**. Unlike other keys, you can reveal it again at any time.

Use it to try the API. For anything that runs unattended, create a key of its own with only the scopes it needs.

## Create a key

1. Sign in to the Orbbit console and open **API Keys**.
2. Click **New Key**.
3. Under **Name**, give the key a name you'll recognize later, such as `cost-dashboard-prod`.
4. Under **Spend budget (USD)**, set the most this key may spend in a month. Once it has spent that much, its calls are refused with `402` until the next calendar month starts (in UTC), even if your balance has money left.
5. Under **Scope**, tick the endpoints the key may call. A key can only call the endpoints you tick.
6. Click **Create**, then copy the key from the **Save your key** window.

> [!WARNING]
>
> The console shows the full key only once. Orbbit stores a one-way fingerprint of it, not the key itself, so nobody, including Orbbit, can show it to you again. If you lose it, revoke it and create a new one.

The key list shows the last four characters of each key so you can tell them apart.

## Choose what a key may call

Each endpoint needs its own permission, called a scope. Give each key only the scopes it needs: a leaked key that can only search branded foods can do far less harm than one that can call everything.

| Scope | Lets the key call |
| - | - |
| `search-commodities` | [`GET /v1/commodities`](https://data-docs.orbbit.co/api-reference/commodities/list-commodities) |
| `get-commodity-prices` | [`GET /v1/commodities/metric-values`](https://data-docs.orbbit.co/api-reference/commodities/get-commodity-metric-values) |
| `search-branded-foods` | [`GET /v1/branded-foods`](https://data-docs.orbbit.co/api-reference/branded-food/search-branded-foods) and [`GET /v1/branded-foods/categories`](https://data-docs.orbbit.co/api-reference/branded-food/list-branded-food-categories) |
| `get-branded-foods` | [`GET /v1/branded-foods/{id}`](https://data-docs.orbbit.co/api-reference/branded-food/get-a-branded-food) |

The console labels each scope in plain words. For example, `get-commodity-prices` shows as **Get Commodity Metric Values**. You can change a key's name, budget, and scopes at any time from **API Keys**. The key itself stays the same.

## When a key is refused

| Status | `error.type` | Why | What to do |
| - | - | - | - |
| `401` | `unauthorized` | The header is malformed, or the key is unknown or revoked. | Check the header reads `Bearer ` followed by the full key. |
| `402` | `insufficient_balance` | Your balance, or this key's monthly spend budget, can't cover the call. | Top up on **Balance**, or raise the key's budget. See [Pricing & Billing](https://data-docs.orbbit.co/pricing.md). |
| `403` | `forbidden` | The key is valid but does not have this endpoint's scope. | Add the scope to the key in the console. |

```json 403 Missing scope theme={null}
{
  "error": {
    "type": "forbidden",
    "message": "This key is not scoped to get-commodity-prices"
  }
}
```

See [Errors](https://data-docs.orbbit.co/errors.md) for every error the API returns.

## Revoke a key

Open **API Keys**, find the key by its name and last four characters, and click **Revoke**. Requests using it are refused with `401` straight away. Revoking cannot be undone.

## Keep keys safe

* Call the API from your server, never from a browser or mobile app, where anyone can read the key.
* Store keys in a secrets manager or environment variable, not in source code.
* Use a separate key for each app and environment, so you can revoke one without breaking the others.


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