Skip to main content
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

1

Open the Dashboard

Log in to your Hany account at hany.tools and go to the main dashboard.
2

Navigate to API Keys

Click on Settings in the left sidebar, then select API Keys from the settings menu.
3

Generate a New Key

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.
4

Copy and Store the Key

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. 
curl -X GET https://api.hany.tools/v1/sms/sender-ids \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/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.
Terminal
export HANY_API_KEY="your_api_key_here"
JavaScript
const apiKey = process.env.HANY_API_KEY;
Python
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.
.gitignore
# 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 CodeErrorMeaningHow to Fix
401 Unauthorizedinvalid_api_keyThe 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 <key> header. Verify the key in your dashboard under Settings → API Keys.
401 Unauthorizedapi_key_revokedThe 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 Forbiddeninsufficient_permissionsThe 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 Forbiddenaccount_suspendedYour Hany account has been suspended.Contact Hany support to resolve the suspension before making further API calls.
An authentication error response looks like this:
401 Unauthorized
{
  "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.