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

​
Create a key

  1. In Watchdog, 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: 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:
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.
Keys created for a single organization before personal API keys existed may leave out X-Organization-Id. They only work in that organization.

​
Access levels

Each API key has one access level. Higher levels include everything the lower ones allow. 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

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.