Authentication

Secure your API requests with Bearer token authentication. All endpoints require a valid API key in the Authorization header.

Overview

Hoko uses Bearer token authentication for all API requests. This industry-standard approach ensures secure access to your workspace data while keeping implementation simple.

Every API request must include a valid API key in the Authorization header. API keys are scoped to specific permissions, allowing you to follow the principle of least privilege.

Bearer Token Authentication

Include your API key in every request using the Authorization header with the Bearer scheme. The API key should be placed immediately after "Bearer " (note the space).

Both the full format "Bearer " and just the API key itself are accepted for convenience.

Header Format text 
Authorization: Bearer <API_KEY>
curl Example cURL 
curl -X GET "https://hoko.to/api/links" \
  -H "Authorization: Bearer <API_KEY>"
JavaScript (fetch) JavaScript 
fetch('https://hoko.to/api/links', {
  headers: {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
  }
})
Python (requests) python 
import requests

headers = {
    'Authorization': 'Bearer <API_KEY>',
    'Content-Type': 'application/json'
}

response = requests.get('https://hoko.to/api/links', headers=headers)

Security Best Practice

Never expose your API keys in client-side code, public repositories, or shared documents. Always store API keys securely using environment variables or secret management services.

Authentication Errors

  • Missing Authorization header - The request doesn't include an Authorization header
  • Invalid API key format - The API key format is incorrect or malformed
  • Invalid or revoked key - The API key doesn't exist, has been revoked, or belongs to a different workspace
  • Expired key - The API key has expired (if expiration is configured)

When authentication fails, the API returns a 401 Unauthorized status code with a descriptive error message. Understanding these errors helps you troubleshoot authentication issues quickly.

Error Response json 
{
  "error": {
    "en": "Invalid API key",
    "ar": "مفتاح API غير صالح"
  }
}

Troubleshooting

If you receive a 401 error, verify that your API key is correct, hasn't been revoked, and is included in the Authorization header. Check your workspace settings to ensure the key is active and has the required scopes.