API Keys

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

Overview

API keys are the primary method of authenticating requests to the Hoko API. Each key is associated with your workspace and can be configured with specific permission scopes, allowing you to control exactly what operations each key can perform.

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

Once you have an API key, include it in every API request using the Authorization header with the Bearer scheme. The API will validate the key and check that it has the required scopes for the requested operation.

Header Format text 
Authorization: Bearer <API_KEY>
curl Example cURL 
curl -X GET "https://hoko.to/api/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.