API Keys

Create and manage API keys with granular permission scopes. Secure your integrations with the principle of least privilege.

Overview

API keys are one supported credential for Hoko API requests. You can also use a human token, an OAuth access token, or an authenticated browser session. Each API key is associated with your workspace and can be configured with specific permission scopes.

This granular access control enables you to create different keys for different purposes—for example, a read-only key for analytics dashboards, or a write key for automated link creation scripts.

Creating API Keys

Create new API keys from your workspace dashboard under Settings > Integrations > API Keys. When creating a key, you'll need to:

  1. Provide a descriptive name to help you identify the key's purpose

  1. Select the appropriate permission scopes based on what operations the key needs to perform

  1. Copy the key immediately after creation—it will only be displayed once for security reasons

Important Security Notice

API keys are displayed only once during creation. If you lose a key, you must revoke it and create a new one. Never share API keys publicly or commit them to version control.

Permission Scopes

  • linksRead - Read and list links (GET /links)
  • linksWrite - Create, update, and delete links (POST, PUT, DELETE /links)
  • collectionsRead - Read and list collections (GET /collections)
  • collectionsWrite - Create, update, and delete collections (POST, PUT, DELETE /collections)
  • tagsRead - Read and list tags (GET /tags)
  • tagsWrite - Create, update, and delete tags (POST, PUT, DELETE /tags)
  • analyticsRead - Access click analytics and performance data (GET /analytics)
  • conversionsWrite - Track lead and sale conversion events (POST /track/lead, POST /track/sale)
  • customersRead - Read customer data (GET /customers)
  • customersWrite - Update and delete customer data (PUT, DELETE /customers)
  • partnersRead - Read partner data (GET /partners)
  • partnersWrite - Create, update, and delete partners (POST, PUT, DELETE /partners)

Scopes define what operations an API key can perform. By granting only the minimum required permissions, you follow security best practices and limit potential damage if a key is compromised.

Each scope is independent—you can combine multiple scopes to create keys with exactly the permissions you need.

Best Practice

Create separate API keys for different environments (development, staging, production) and different use cases (read-only monitoring, automated link creation, conversion tracking). This makes it easier to rotate keys and audit access.

Using API Keys

Use one credential on each request. The API validates the credential and checks the scopes required by the operation.

Header Format text 
Authorization: Bearer <API_KEY>

You can send an API key in the alternate header:

Code text 
X-API-Key: <API_KEY>

For a human token or OAuth access token, replace <API_KEY> with the access token. First-party browser requests may use the authenticated session cookie.

curl Example cURL 
curl -X GET "https://api.hoko.to/links" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json"

Revoking API Keys

You can revoke API keys at any time from your workspace settings. Revocation is immediate and permanent—revoked keys cannot be restored or reactivated.

Revoke keys immediately if you suspect they've been compromised, or when they're no longer needed. This is a critical security practice, especially when keys are used in production environments.

Security Alert

If an API key is exposed or compromised, revoke it immediately and create a new one. Monitor your API usage logs for any suspicious activity after key revocation.