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

# Authenticate with the Hany API Using API Bearer Tokens

> All Hany API requests require an API key passed as a Bearer token in the Authorization header. Learn how to generate and use your API key.

Every request you make to the Hany API must be authenticated. Hany uses API keys passed as Bearer tokens in the `Authorization` request header. Without a valid key, all requests return a `401 Unauthorized` response. There are no cookies, sessions, or OAuth flows — just a single, portable key per integration.

## Getting Your API Key

<Steps>
  <Step title="Log in to your Hany dashboard">
    Go to [https://hany.tools](https://hany.tools) and sign in to your account.
  </Step>

  <Step title="Open API Keys settings">
    Navigate to **Settings → API Keys** from the left sidebar.
  </Step>

  <Step title="Generate a new key">
    Click **"Generate New Key"**, give it a descriptive label (e.g., `production-backend`), and confirm.
  </Step>

  <Step title="Copy and store your key securely">
    Copy the key immediately and store it somewhere safe — such as a password manager or secrets vault. For security reasons, the full key is **not shown again** after you leave this screen.
  </Step>
</Steps>

## Using Your API Key

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

```bash theme={null}
curl -X POST https://api.hany.tools/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+233XXXXXXXXX", "from": "YourBrand", "message": "Hello!"}'
```

The same pattern applies to every endpoint — swap out the path and request body as needed.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.hany.tools/v1/sms/send', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HANY_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+233XXXXXXXXX',
      from: 'YourBrand',
      message: 'Hello!'
    })
  });

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

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

  response = requests.post(
      'https://api.hany.tools/v1/sms/send',
      headers={
          'Authorization': f'Bearer {os.environ["HANY_API_KEY"]}',
          'Content-Type': 'application/json'
      },
      json={
          'to': '+233XXXXXXXXX',
          'from': 'YourBrand',
          'message': 'Hello!'
      }
  )

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

## Security Best Practices

Keeping your API key secure protects your account, your credits, and your recipients. Follow these practices in every integration:

* **Use environment variables** — read your key from `process.env` or `os.environ` rather than hard-coding it in your source files.
* **Never commit API keys to version control** — add `.env` files to your `.gitignore` and use secrets management tools in CI/CD pipelines.
* **Use one key per integration or environment** — separate keys for development, staging, and production make it easy to rotate or revoke a single key without affecting other environments.
* **Rotate compromised keys immediately** — go to **Settings → API Keys** in the dashboard, revoke the affected key, and generate a replacement.

<Warning>
  Never expose your API key in client-side code (browser JavaScript). Anyone who can view your page source or network requests will be able to read it. Always make API calls from a server-side environment.
</Warning>

## Authentication Errors

If your request is rejected due to an authentication problem, you will receive one of the following responses:

| HTTP Status        | Error Code     | Meaning                                                                                |
| ------------------ | -------------- | -------------------------------------------------------------------------------------- |
| `401 Unauthorized` | `unauthorized` | The `Authorization` header is missing, malformed, or contains an invalid API key.      |
| `403 Forbidden`    | `forbidden`    | The API key is valid, but it does not have permission to perform the requested action. |

See the [Errors](/api-reference/errors) page for the full error response format and a complete list of error codes.