Skip to main content

Authentication

Woodpecker API follows a unified authentication mechanism across all endpoints, but when managing multiple accounts, you need to consider the company context. Your API requests may operate at different levels:

  • HQ account (your main company account)
  • Client accounts (individual accounts you manage)

This guide covers general authentication and multi-account management using the HQ API key and the master API key.

Generating an API key​

To authenticate requests, you must first generate an API key. Click here to go to the API keys view of your HQ. You can also follow the instructions below; the process is the same for your HQ account and client accounts:

  1. Log into the Woodpecker account where you want to generate an API key (either your HQ account or a client account)
  2. Go to the Marketplace in the top-right corner → Integrations → 'API keys'
  3. Click Create a key
  4. You can add a label to each created key to describe what integration it is being used for

API keys are user-specific, meaning each user only sees their own keys. Keep them private and do not share them with others.

Authenticating requests​

The base URL is:

https://api.woodpecker.co/rest

All requests need to be authenticated using an x-api-key header. Try the request below, making sure to replace YOUR_API_KEY with your actual key. Note the difference in the response when using an Agency HQ API key versus a client account API key or master API key.

curl --request GET \
  --url "https://api.woodpecker.co/rest/v1/me" \
  --header "x-api-key: {YOUR_API_KEY}"

Company context​

When working across multiple accounts, you have two ways to authenticate requests:

  1. Using a dedicated API key for each account - generate a separate API key for each client, with the key operating only within given account. (Use rest/v2/agency/companies/{cid}/api_keys to generate client keys via API)
  2. Using the HQ API key with x-company-id header - send requests on behalf of different accounts without switching API keys. Include the x-company-id header to specify which account's data you are accessing. This is described further below.

Use the HQ API key for managing multiple accounts. For endpoints that interact with specific accounts, either use a client's API key or specify x-company-id.

tip

Use the HQ API key for /agency endpoints. To access the Cold Email API for a specific client, choose one of the methods above.

Using master API key​

The HQ API key allows managing multiple accounts with a single key. To make use of this functionality, you need:

Example requests​

Lets consider an example where you want to retrieve mailboxes connected to company ID 123. You can:

  • Use an API key generated for this company
curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/mailboxes" \
  --header "x-api-key: API_KEY_COMPANY_123"
  • Use the HQ API key together with the x-api-key header
curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/mailboxes" \
  --header "x-api-key: HQ_API_KEY" \
  --header "x-company-id: 123"
  • A similar request without the x-api-key header will return mailboxes connected to your HQ account
curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/mailboxes" \
  --header "x-api-key: HQ_API_KEY"
curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/agency/companies/123/email_accounts" \
  --header "x-api-key: HQ_API_KEY"

Error codes​

x-company-id provided but not numeric

{
  "title": "Bad request",
  "status": 400,
  "detail": "X-Company-Id header value must be a number but is not",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema​

FieldTypeDescription
titlestringA short title describing the error
statusintegerThe HTTP status code
detailstringA detailed message explaining the error
timestampstringThe timestamp when the error occurred, YYYY-MM-DD HH:MM:SS UTC