> ## 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.
# Hany API Authentication: Managing Keys and Securing Access
> Hany uses Bearer token API keys to authenticate every request. Learn how to generate your key, pass it correctly, and keep it secure.
Hany authenticates every API request using **Bearer token authentication**. You include your API key in the `Authorization` header of each request, and Hany verifies your identity, checks your account permissions, and routes the request accordingly. No OAuth flows, no session cookies — just a single header on every call.
## Getting Your API Key
Log in to your Hany account at [hany.tools](https://hany.tools) and go to the main dashboard.
Click on **Settings** in the left sidebar, then select **API Keys** from the settings menu.
Click **Generate New Key**. Give the key a descriptive label — for example, `production-api` or `mobile-app-backend` — so you can identify its purpose at a glance.
Copy the key immediately. Hany displays the full key only once at creation time. If you lose the key before storing it, you'll need to revoke it and generate a new one.
Store the key in a secrets manager, a `.env` file that is excluded from version control, or your hosting provider's environment variable system.
## Making Authenticated Requests
Pass your API key as a Bearer token in the `Authorization` header of every request. The example below calls `GET /sms/sender-ids` to list your registered Sender IDs — you can substitute any other endpoint in the same way.
```bash cURL theme={null}
curl -X GET https://api.hany.tools/v1/sms/sender-ids \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.hany.tools/v1/sms/sender-ids", {
method: "GET",
headers: {
"Authorization": `Bearer ${process.env.HANY_API_KEY}`,
"Content-Type": "application/json",
},
});
const data = await response.json();
console.log(data);
```
```python Python theme={null}
import os
import requests
response = requests.get(
"https://api.hany.tools/v1/sms/sender-ids",
headers={
"Authorization": f"Bearer {os.environ['HANY_API_KEY']}",
"Content-Type": "application/json",
},
)
print(response.json())
```
## API Key Security
Protecting your API key is your responsibility. A compromised key gives anyone full access to your Hany account, including the ability to send messages that consume your credits. Follow these practices to keep your keys safe.
### Use Environment Variables
Never hard-code your API key in source code. Instead, load it from an environment variable at runtime.
```bash Terminal theme={null}
export HANY_API_KEY="your_api_key_here"
```
```javascript JavaScript theme={null}
const apiKey = process.env.HANY_API_KEY;
```
```python Python theme={null}
import os
api_key = os.environ["HANY_API_KEY"]
```
### Never Commit Keys to Version Control
Add `.env` files and any files containing secrets to your `.gitignore` before your first commit. Once a secret is pushed to a repository — even a private one — treat it as compromised and rotate it immediately.
```bash .gitignore theme={null}
# Environment variables
.env
.env.local
.env.*.local
```
### Use Separate Keys per Environment
Generate distinct API keys for development, staging, and production environments. This limits the blast radius if a key is exposed: a leaked development key cannot be used to affect your production account.
### Rotate Compromised Keys Immediately
If you suspect a key has been exposed, go to **Settings → API Keys** in the Hany dashboard, click **Revoke** next to the affected key, and generate a replacement. Update your environment variables and redeploy your application before the old key is fully deactivated.
If your API key is leaked in a public repository, in logs, or in any other accessible location, revoke it immediately in the dashboard and generate a new one. Do not wait to confirm whether the key was actually used — assume it was.
## Authentication Errors
If Hany cannot authenticate your request, the API returns a `4xx` HTTP error code with a JSON body explaining the problem.
| Status Code | Error | Meaning | How to Fix |
| ------------------ | -------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | `invalid_api_key` | The API key is missing, malformed, or does not match any active key in Hany's system. | Check that you are passing the key correctly in the `Authorization: Bearer ` header. Verify the key in your dashboard under **Settings → API Keys**. |
| `401 Unauthorized` | `api_key_revoked` | The API key has been revoked and is no longer valid. | Generate a new key in the dashboard and update your application's environment variables. |
| `403 Forbidden` | `insufficient_permissions` | The API key is valid but does not have permission to perform the requested action. | Check the key's permission scope in the dashboard. Some actions require keys with elevated permissions. |
| `403 Forbidden` | `account_suspended` | Your Hany account has been suspended. | Contact [Hany support](https://hany.tools) to resolve the suspension before making further API calls. |
An authentication error response looks like this:
```json 401 Unauthorized theme={null}
{
"status": "error",
"code": "invalid_api_key",
"message": "The API key provided is invalid or has been revoked.",
"docs_url": "https://docs.hany.tools/authentication"
}
```
If you are consistently receiving `401` errors after generating a fresh key, make sure there are no leading or trailing whitespace characters in the key value — this is a common copy-paste issue. Use your programming language's string trim function to strip whitespace before passing the key to the `Authorization` header.