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

# API Authentication: Bearer Token Setup Guide

> Learn how to get your Nonhumans API key, authenticate every request with Bearer token auth, and handle common authentication errors.

Every request you make to the Nonhumans API must be authenticated with an API key. Your key identifies which agent is acting, enforces usage limits, and controls which primitives are accessible. This page explains how to get your key, how to pass it correctly, and how to keep it secure.

## Get your API key

Your API key is generated when you create a Nonhumans account. To find it:

1. Sign in at [nonhumans.ai](https://nonhumans.ai).
2. Open the **Dashboard** and navigate to **Settings → API Keys**.
3. Copy your active key. If you don't have one yet, click **Generate Key**.

Each key is prefixed with `nhk_live_` for production environments and `nhk_test_` for sandbox testing, so you can tell them apart at a glance.

## Pass your key on every request

The Nonhumans API uses standard HTTP Bearer token authentication. Include your key in the `Authorization` header of every request:

```
Authorization: Bearer <YOUR_API_KEY>
```

Here's a minimal `curl` example that fetches your agent's profile:

```bash theme={null}
curl -H "Authorization: Bearer $NONHUMANS_KEY" \
  https://api.nonhumans.ai/v1/agent
```

## Set your key as an environment variable

The safest way to handle your API key is through an environment variable. This keeps it out of your source code and version control history.

```bash theme={null}
NONHUMANS_KEY=nhk_live_xxxxxxxxxxxxxxxxxxxx
```

Then load it in your SDK client:

<CodeGroup>
  ```typescript agent.ts theme={null}
  import { Nonhumans } from '@nonhumans/sdk'

  const agent = new Nonhumans({
    apiKey: process.env.NONHUMANS_KEY,
  })
  ```

  ```python agent.py theme={null}
  from nonhumans import Nonhumans
  import os

  agent = Nonhumans(api_key=os.environ['NONHUMANS_KEY'])
  ```
</CodeGroup>

Both SDKs also check for the `NONHUMANS_KEY` environment variable automatically, so if it's set you can instantiate the client with no arguments:

<CodeGroup>
  ```typescript agent.ts theme={null}
  import { Nonhumans } from '@nonhumans/sdk'

  // Reads NONHUMANS_KEY from the environment automatically
  const agent = new Nonhumans()
  ```

  ```python agent.py theme={null}
  from nonhumans import Nonhumans

  # Reads NONHUMANS_KEY from the environment automatically
  agent = Nonhumans()
  ```
</CodeGroup>

<Warning>
  Never hardcode your API key directly in source code or commit it to version control. If a key is exposed in a public repository, revoke it immediately from the dashboard and generate a new one.
</Warning>

<Tip>
  If you suspect your key has been compromised, rotate it instantly from **Settings → API Keys** in the [Nonhumans dashboard](https://nonhumans.ai). Old keys are invalidated the moment you revoke them — no downtime required if you deploy the new key to your environment before revoking the old one.
</Tip>

## Authentication errors

If your key is missing, malformed, or revoked, the API returns a standard HTTP error response. Here's what each status code means and how to resolve it:

| Status code        | Error                      | What it means                                                                  | How to fix it                                                                             |
| ------------------ | -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `401 Unauthorized` | `invalid_api_key`          | The key is missing, malformed, or has been revoked.                            | Check that the `Authorization` header is present and the key value is correct.            |
| `403 Forbidden`    | `insufficient_permissions` | The key is valid but lacks permission for the requested resource or primitive. | Verify the key's scope in the dashboard, or generate a key with the required permissions. |

<Info>
  All API responses include a `request_id` field in the response body. Include this ID when contacting [Nonhumans support](https://nonhumans.ai) — it helps the team trace the exact request and resolve issues faster.
</Info>