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

# Authentication

> Key types, how to send them, and how access is checked.

All API requests are authenticated with an API key sent as a bearer token.

```bash theme={null}
curl -sS "https://api.geoptie.com/v1/brands" \
  -H "Authorization: Bearer $GEOPTIE_API_KEY"
```

## API key types

Geoptie offers two types of API key.

**Workspace keys**

* Access every brand in your workspace
* Can create new brands
* Recommended for most use cases

**Brand-scoped keys**

* Limited to the brands you choose
* Useful for giving a client or an internal team access to only their own data
* Cannot create new brands

A brand-scoped key behaves as though the other brands do not exist. `GET /v1/brands` returns
only the brands in its scope, and anything outside that scope returns `404`. If a brand is
later removed from your workspace, it drops out of the key's scope too.

## Creating an API key

1. Go to **API keys** in the dashboard sidebar.
2. Click **Create API key**.
3. Choose the key type, and the brands if you are creating a scoped key.
4. Copy and securely store the key.

<Warning>
  The key is shown only once, when you create it. If you lose it, revoke the key and create a
  new one.
</Warning>

Keys belong to the workspace rather than to an individual, so they keep working as team
members come and go. Create a separate key per integration so you can revoke one without
affecting the others. Revoking takes effect within a minute.

## Validating a key

`GET /v1/brands` is the cheapest call that proves a key works. A `200` means the key is
valid and the subscription is active; the brands it returns are the ones this key can reach.

```bash theme={null}
curl -sS "https://api.geoptie.com/v1/brands" \
  -H "Authorization: Bearer $GEOPTIE_API_KEY"
```

## Access requirements

Your workspace needs an active or trialing subscription, and access is checked on every
request.

| Response                    | Meaning                               | What to do                      |
| --------------------------- | ------------------------------------- | ------------------------------- |
| `401 missing_api_key`       | No `Authorization` header             | Add the header                  |
| `401 invalid_api_key`       | Key is unknown or revoked             | Create a new key                |
| `402 subscription_required` | Subscription inactive or past due     | Update billing in the dashboard |
| `403 plan_not_eligible`     | Your plan does not include API access | Upgrade, or contact support     |
| `403 brand_scope_forbidden` | A scoped key tried to create a brand  | Use a workspace key             |

## Keeping your key safe

* Store keys in a secret manager or an environment variable, never in source control.
* The API is server to server. Do not use a key in a browser or mobile app, where anyone can
  read it.
* Use brand-scoped keys when an integration only needs one brand.
* Revoke immediately if a key is exposed.

## Need help

Email [support@geoptie.com](mailto:support@geoptie.com).