Authentication

All Hozip API endpoints require an API key. This page explains how to generate one and how to include it in every request.

How authentication works

Hozip uses token-based authentication. Each account has exactly one API key. You pass it in the Authorization header of every request: 

Authorization: Token YOUR_API_KEY
The prefix is Token, not Bearer. Using Bearer will result in a 401 Unauthorized response.

Step 1 — Generate your API key

  1. Log in to your Hozip account.
  2. Go to Profile → API Keys (or navigate directly to /profile/api-key/).
  3. Click Generate key.
  4. Your API key is displayed once in plain text. Copy it immediately and store it somewhere safe — after you leave or refresh the page it will only appear masked (e.g. a1b2c3d4...xyz789).
Copy your key now. Hozip does not store keys in recoverable form. If you lose it, you must regenerate a new one (which invalidates the old one).

Step 2 — Use the key in requests

Add the Authorization: Token YOUR_API_KEY header to every call.

cURL

curl -H "Authorization: Token YOUR_API_KEY" \
https://hozip.com/api/v1/external/groups

Python (requests)

import requests
API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Token {API_KEY}"}

resp = requests.get(
    "https://hozip.com/api/v1/external/groups",
    headers=HEADERS,
)
resp.raise_for_status()
print(resp.json())

Node.js (fetch)

const API_KEY = "YOUR_API_KEY";
const resp = await fetch("https://hozip.com/api/v1/external/groups", {
  headers: { Authorization: `Token ${API_KEY}` },
});
const data = await resp.json();
console.log(data);

PHP (cURL)

<?php
$apiKey = "YOUR_API_KEY";
$ch = curl_init("https://hozip.com/api/v1/external/groups");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Token $apiKey",
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Managing your key

Action Where What happens
Generate Profile → API Keys → Generate key Creates your first key. Shown in plain text only at this moment.
Regenerate Profile → API Keys → Regenerate key Deletes the existing key and creates a brand-new one. The old key stops working immediately. Any integration using the old key will start receiving 401 responses and must be updated.
Revoke Profile → API Keys → Revoke key Permanently deletes the key with no replacement. All API access using that key stops immediately. You can generate a new one at any time.

Error responses

Status Cause Fix
401 Missing Authorization header, wrong prefix (Bearer instead of Token), revoked key, or malformed token. Check that the header reads exactly Authorization: Token <key> and that the key has not been revoked.
403 Valid key but the account does not have permission to perform the action. Contact support if you believe this is unexpected.

Security recommendations

  • Never embed your key in client-side or public code (browser JavaScript, mobile apps, public repositories). API calls should always be made server-side.
  • Use environment variables to inject the key at runtime rather than hardcoding it in source files.
  • Rotate periodically. Use Regenerate to issue a new key on a regular schedule and update your integrations.
  • Revoke immediately if you suspect the key has been compromised.

Ready to make your first call? Head to the Groups or Create Link endpoint pages for complete examples.

Documentation