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

# Authentication and API keys

> Create an API key and send it with your requests.

Every request to the Watchdog API sends an API key and the organization it works in.

```http theme={null}
Authorization: Bearer <your API key>
X-Organization-Id: org_<organization ID>
```

## Create a key

1. In [Watchdog](https://app.watchdog.no), open **Settings → Personal → API keys** and choose
   **Create API key**.
2. Give the key a name you will recognize later.
3. Choose an [access level](#access-levels): **Read** to read data, **Write** to also upload
   and change data, or **Admin** to also manage the organization.
4. Choose which organizations the key can use: **All organizations you have access to** or **Only
   selected organizations**.
5. Copy the key and store it safely. It is shown only once.

**All organizations** includes organizations you join later. **Only selected organizations** never
reaches beyond the ones you pick.

API keys belong to you. A key can never do more than you can do yourself in that organization, and
it stops working there if you leave the organization.

## Send the key

Open your organization in Watchdog. The organization ID is the `org_…` part of the address. Send it
with your key on every request:

```bash theme={null}
export API_URL=https://api.watchdog.no
export API_KEY='<your API key>'
export ORGANIZATION_ID='<your org_… ID>'

curl "$API_URL/v1/invoices" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Organization-Id: $ORGANIZATION_ID"
```

A key that works in several organizations still works in one organization per request.
`GET /v1/organizations` without the `X-Organization-Id` header lists the organizations your key
can use. Read the current organization and your effective access with `GET /v1/organization`,
using its ID in `X-Organization-Id`.

<Note>
  Keys created for a single organization before personal API keys existed may leave out
  `X-Organization-Id`. They only work in that organization.
</Note>

## Access levels

Each API key has one access level. Higher levels include everything the lower ones allow.

| Level | What the key can do |
| - | - |
| **Read** | Read data and download documents. |
| **Write** | Everything in Read, plus upload, create, change, and delete data. |
| **Admin** | Everything in Write, plus organization settings such as members, integrations, and usage. |

Choose **Read** for reporting and **Write** for uploading invoices or changing data. Only choose
**Admin** if the integration manages the organization itself.

A key never has more access than you do. Organization members can use at most **Write**; only
organization admins can use **Admin**. For example, an Admin key used in an organization where you
are a member works as a Write key there.

## When a request is refused

| Status | Meaning |
| - | - |
| `401` | The key is missing, wrong, or revoked. |
| `403` | The key is valid but not allowed: it has no access to the organization, `X-Organization-Id` is missing, or its access level is too low for what you asked to do. |

If the organization requires multi-factor authentication, turn it on for your Watchdog account;
until then your keys are refused there with `403`.

## Change, rotate, or revoke a key

Open the key under **Settings → Personal → API keys** and use the **…** menu:

* **Edit API key** changes its name, access level, or organizations. The key itself stays the same.
* **Revoke API key** stops the key immediately. This cannot be undone.

To rotate a key, create a new one, switch your integration over, and then revoke the old one.

## Keep keys safe

* Keep keys on your server, in a secrets manager or environment variable.
* Never put them in source control, logs, screenshots, or code that runs in a browser.
* Watchdog can't show a key again. If you lose one, create a new key and revoke the old one.


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