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

# API Authentication and API Key Management

> NZOChain API uses bearer token authentication. Learn how to get your API key, pass it in requests, and handle authentication errors.

Every request to the NZOChain API must include a valid API key. Authentication uses the standard HTTP bearer token scheme — you pass your key in the `Authorization` header of each request. There are no cookies, sessions, or OAuth flows to set up.

## Getting your API key

1. Log in to the [NZOChain dashboard](https://app.nzochain.com).
2. Go to **Settings → API Keys**.
3. Click **Generate new key** and copy the value immediately — it is only shown once.

If you lose your key, you can revoke it and generate a new one from the same page.

## Passing your API key

Include your key as a bearer token in the `Authorization` header on every request:

```bash theme={null}
curl -X POST https://api.nzochain.com/v1/api/risk/scan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet": "0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234"}'
```

## Code examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.nzochain.com/v1/api/risk/scan \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"wallet": "0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.nzochain.com/v1/api/risk/scan', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.NZOCHAIN_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      wallet: '0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234',
    }),
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      'https://api.nzochain.com/v1/api/risk/scan',
      headers={
          'Authorization': f'Bearer {os.environ["NZOCHAIN_API_KEY"]}',
          'Content-Type': 'application/json',
      },
      json={
          'wallet': '0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234',
      },
  )

  print(response.json())
  ```
</CodeGroup>

## Authentication errors

| HTTP status        | Cause                                                     | Resolution                                                                               |
| ------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `401 Unauthorized` | API key is missing, malformed, or has been revoked        | Check that your `Authorization` header is present and formatted as `Bearer YOUR_API_KEY` |
| `403 Forbidden`    | Key is valid but your plan does not include this endpoint | Upgrade your plan or check endpoint availability in the [API Overview](/api/overview)    |

## Security best practices

* **Use environment variables.** Store your API key in an environment variable (e.g., `NZOCHAIN_API_KEY`) and read it at runtime. Never hard-code it in your source files.
* **Keep keys server-side.** Never include your API key in client-side JavaScript, mobile app bundles, or any code that is shipped to end users.
* **Rotate keys periodically.** Regenerate your API key on a regular schedule and immediately after any suspected exposure.
* **Use separate keys per environment.** Generate distinct keys for development, staging, and production so you can revoke one without affecting the others.

<Warning>
  Never commit your API key to source control. If a key is accidentally committed, revoke it immediately from the NZOChain dashboard and generate a replacement. Treat any exposed key as compromised.
</Warning>