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

# How to Authenticate Doohick API Requests with API Keys

> Learn how to generate Doohick API keys, pass them as Bearer tokens in every request, keep them secure, and troubleshoot authentication errors.

Every request to the Doohick API must be authenticated. Doohick uses API keys passed as Bearer tokens in the `Authorization` header — there are no session cookies or OAuth flows required for server-to-server calls. Generate a key from your dashboard, attach it to each request, and you are ready to go.

## Generating an API key

Follow these steps to create a new API key from your Doohick dashboard:

<Steps>
  <Step title="Log in to Doohick">
    Navigate to [app.doohick.com](https://app.doohick.com) and sign in to your account.
  </Step>

  <Step title="Open Settings">
    Click your profile avatar in the top-right corner, then select **Settings** from the dropdown.
  </Step>

  <Step title="Go to API Keys">
    In the left sidebar, select **API Keys** under the Developer section.
  </Step>

  <Step title="Generate a new key">
    Click **Generate New Key** to open the key creation dialog.
  </Step>

  <Step title="Name your key">
    Enter a descriptive name — for example, `Production Backend` or `CI Pipeline` — so you can identify the key's purpose later.
  </Step>

  <Step title="Copy and store the key securely">
    Copy the key immediately and store it in a secrets manager or environment variable. Doohick only displays the full key value once at creation time.
  </Step>
</Steps>

API keys follow this format:

```text theme={null}
dh_live_XXXXXXXXXXXXXXXXXXXX
```

## Using your API key

Pass your API key as a Bearer token in the `Authorization` header of every request:

```bash theme={null}
curl -X GET https://api.doohick.com/v1/users \
  -H "Authorization: Bearer dh_live_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json"
```

The `Authorization` header is required on all endpoints. Requests that omit it receive a `401 Unauthorized` response.

## Key types

Doohick issues two types of API keys, each scoped to a different environment:

* **Live keys** (`dh_live_...`) — use these in production. Operations performed with a live key affect real data and may trigger billing.
* **Test keys** (`dh_test_...`) — use these during development and testing. Operations performed with a test key are sandboxed and do not affect your live data or account state.

Both key types share the same endpoints and request format. The prefix (`live` vs `test`) determines which environment processes the request.

## Keeping your key secure

<Warning>
  Never embed API keys directly in frontend JavaScript, mobile app binaries, or version-controlled source code. Anyone who obtains your key can make authenticated API calls on your behalf. If a key is ever exposed, revoke it immediately.
</Warning>

Store your keys in environment variables and read them at runtime:

```bash theme={null}
export DOOHICK_API_KEY="dh_live_XXXXXXXXXXXXXXXXXXXX"
```

```javascript theme={null}
const apiKey = process.env.DOOHICK_API_KEY;
```

For team environments, use a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or your CI provider's encrypted secrets store.

## Revoking a key

To revoke an API key, go to **Settings → API Keys** in your Doohick dashboard and click **Revoke** next to the key you want to invalidate. Revocation is immediate — all in-flight and future requests using that key receive a `401` response. Issue a new key before revoking the old one if you need zero-downtime rotation.

## Authentication errors

The table below lists the authentication-related error codes you may encounter:

| Status | Error code           | Meaning                                       |
| ------ | -------------------- | --------------------------------------------- |
| 401    | `missing_token`      | No `Authorization` header was included        |
| 401    | `invalid_token`      | The key is invalid or malformed               |
| 401    | `expired_token`      | The key has been revoked                      |
| 403    | `insufficient_scope` | The key lacks the permissions for this action |

<Tip>
  Always use a test key (`dh_test_...`) during development. This lets you exercise the full API surface without touching production data, and makes it safe to iterate quickly without risk of unintended side effects.
</Tip>