> ## Documentation Index
> Fetch the complete documentation index at: https://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.

Every request needs an API key in the `Authorization` header:

```bash theme={null}
curl --request GET \
  --url https://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.

## 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.
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.
</Warning>

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 stores can do far less harm than one that can call everything.

| Scope                   | Lets the key call                                                                                                                                                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search-commodities`    | [`GET /v1/commodities`](/api-reference/commodities/search-commodity-series)                                                                                       |
| `get-commodity-prices`  | [`GET /v1/commodities/prices`](/api-reference/commodities/get-commodity-prices)                                                                                   |
| `search-branded-foods`  | [`GET /v1/branded-foods`](/api-reference/branded-food/search-branded-foods) and [`GET /v1/branded-foods/categories`](/api-reference/branded-food/list-categories) |
| `get-branded-foods`     | [`GET /v1/branded-foods/{id}`](/api-reference/branded-food/get-a-branded-food)                                                                                    |
| `search-stores`         | [`GET /v1/stores`](/api-reference/shopify/search-stores)                                                                                                          |
| `get-store`             | [`GET /v1/stores/{id}`](/api-reference/shopify/get-a-store)                                                                                                       |
| `get-store-products`    | [`GET /v1/stores/{id}/products`](/api-reference/shopify/list-store-products)                                                                                      |
| `get-store-collections` | [`GET /v1/stores/{id}/collections`](/api-reference/shopify/list-store-collections)                                                                                |
| `get-product`           | [`GET /v1/products/{id}`](/api-reference/shopify/get-a-product)                                                                                                   |

The console labels each scope in plain words — `get-commodity-prices` shows as **Get Commodity Prices**. 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 missing or malformed, or the key is unknown or revoked. | Check the header reads `Bearer ` followed by the full key. |
| `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](/errors) 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.