Authentication

Secure Hoko requests with an authorized credential: an API key, human token, OAuth access token, or authenticated browser session.

Overview

Hoko authorizes requests through the credential available to the client. Supported authorized access includes an API key, human token, OAuth access token, or authenticated browser session. The client surface and operation determine which credential is appropriate.

API and MCP clients send an access credential in the Authorization header. Browser requests use the authenticated session cookie. The CLI can use browser OAuth for a human account or an API key for automation. Human Tokens are limited to personal Apps connection reads and removal; they do not authorize workspace operations. See API keys for key creation and scope selection.

Bearer Token Authentication

Use an API key when a server-side integration, script, or automation job needs scoped workspace access. Include the key in each 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 <API_KEY> and just the API key itself are accepted for convenience.

Header Format text
Authorization: Bearer <API_KEY>
curl Example cURL
curl -X GET "https://api.hoko.to/links" \
  -H "Authorization: Bearer <API_KEY>"
JavaScript (fetch) JavaScript
fetch('https://api.hoko.to/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://api.hoko.to/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 credential - The request does not include an accepted credential or authenticated session.
  • Invalid credential - The supplied credential is malformed, revoked, expired, or not valid for the target workspace.

When authentication fails, the API returns a 401 Unauthorized status code with a descriptive error message. The exact message identifies the credential or session problem; do not retry with a different credential until its intended client surface and operation are confirmed.

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

Troubleshooting

Check the client surface, credential source, workspace, operation, and required scopes. For an API key, verify that it is active and included in the Authorization header. For browser access, sign in again if the session has expired.