Authenticate with the Hany API Using API Bearer Tokens

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

Go to https://hany.tools and sign in to your account.

Open API Keys settings

Navigate to Settings → API Keys from the left sidebar.

Generate a new key

Click “Generate New Key”, give it a descriptive label (e.g., production-backend), and confirm.

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.

Using Your API Key

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

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.

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);

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)

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.

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.

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 page for the full error response format and a complete list of error codes.

Overview

SMS

Webhooks

Authenticate with the Hany API Using API Bearer Tokens

Getting Your API Key

Using Your API Key

Security Best Practices

Authentication Errors

​Getting Your API Key

​Using Your API Key

​Security Best Practices

​Authentication Errors

Getting Your API Key

Using Your API Key

Security Best Practices

Authentication Errors