Authentication

The H0p API uses API keys for authentication. Each key is scoped to an organization and has configurable permissions, giving you granular control over what each integration can do.

API key overview

API keys provide:

Organization scope - Each key belongs to one organization
Granular permissions - Control exactly what each key can access
Two key types - User keys tied to your account, bot keys tied to your organization
Secure generation - Cryptographically random, shown only once

Key types

H0p offers two types of API keys for different use cases:

User keys
Bot keys

User keys are linked to your personal account:

Property	Description
Limit	One key per user per organization
Attribution	Actions appear under your name
Lifecycle	Deleted when you leave the organization
Best for	Development, testing, personal scripts

# Example: User key for development
x-api-key: h0p_user_abc123...

Bot keys create non-human accounts associated with API keys:

Property	Description
Limit	One bot key per organization
Attribution	Actions appear under “Bot” user
Lifecycle	Survives team member changes
Best for	Integrations that should persist independently of staff

Unlike user keys that are tied to your personal account, bot keys provide organization-scoped credentials that persist independently of staff transitions. This avoids security risks when employees leave or change roles.Bot users don’t count toward your organization’s member limit.

# Example: Bot key
x-api-key: h0p_bot_xyz789...

Creating an API key

Navigate to API Keys

In the dashboard, go to Developer Tools > API Keys.

Click Create API Key

Click the Create API Key button to open the creation form.

Choose key type

Select whether to create a User key or Bot key:

User key - Tied to your account, deleted if you leave the organization
Bot key - Tied to the organization, persists independently of team members

Configure permissions

Select the permissions your key needs. See Permissions below for details.

Follow the principle of least privilege. Only grant permissions your integration actually needs.

Copy your key

Your API key is displayed only once. Copy it immediately and store it securely.

Your API key won’t be shown again. If you lose it, you’ll need to create a new one.

Permissions

API keys use a granular permission system. Each key can be granted specific actions for different resources.

Available resources

Resource	Description
`shortLinks`	Create, read, update, delete short links
`domains`	Manage custom domains
`stats`	Access analytics and click data
`files`	Upload files (QR logos, social images)
`apiKeys`	Manage API keys (admin only)
`webhooks`	Configure webhook endpoints

Available actions

Action	Description
`create`	Create new resources
`read`	View existing resources
`update`	Modify existing resources
`delete`	Remove resources

Example permission configurations

Read-only analytics:

{
  "stats": ["read"],
  "shortLinks": ["read"],
  "domains": ["read"]
}

Link management:

{
  "shortLinks": ["create", "read", "update", "delete"],
  "domains": ["read"],
  "files": ["create", "read"]
}

Full access:

{
  "shortLinks": ["create", "read", "update", "delete"],
  "domains": ["create", "read", "update", "delete"],
  "stats": ["read"],
  "files": ["create", "read", "delete"],
  "webhooks": ["create", "read", "update", "delete"]
}

Using your API key

Include your API key in the x-api-key header with every request:

curl -X GET "https://api.h0p.co/short-link/list?page=0&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

POST request example

curl -X POST "https://api.h0p.co/short-link" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": {
      "type": "link",
      "value": "https://example.com"
    },
    "slug": "my-link"
  }'

Using environment variables

Never hardcode API keys. Use environment variables:

Linux/macOS
Windows (PowerShell)
Node.js
Python

export H0P_API_KEY="your-api-key"

curl -X GET "https://api.h0p.co/short-link/list" \
  -H "x-api-key: $H0P_API_KEY"

$env:H0P_API_KEY = "your-api-key"

curl -X GET "https://api.h0p.co/short-link/list" `
  -H "x-api-key: $env:H0P_API_KEY"

// .env file
H0P_API_KEY=your-api-key

// JavaScript
const apiKey = process.env.H0P_API_KEY;

fetch('https://api.h0p.co/short-link/list', {
  headers: { 'x-api-key': apiKey }
});

import os
import requests

api_key = os.environ['H0P_API_KEY']

response = requests.get(
    'https://api.h0p.co/short-link/list',
    headers={'x-api-key': api_key}
)

Managing API keys

View your keys

See all your organization’s API keys in Developer Tools > API Keys:

The list shows:

Key name and type
Associated user (or “Bot” for bot keys)
Permissions summary
Creation date
Last 4 characters for identification

Update key permissions

Click on a key to open its details
Modify the permissions as needed
Save changes

Revoke a key

If a key is compromised or no longer needed:

Go to Developer Tools > API Keys
Find the key you want to revoke
Click the Delete button
Confirm the deletion

Revoking a key is immediate and irreversible. Any application using this key will stop working instantly.

Security best practices

Store keys securely

Use environment variables, not hardcoded values
Never commit API keys to version control
Use a secrets manager for production (AWS Secrets Manager, HashiCorp Vault, etc.)

# Good
export H0P_API_KEY="your-key"

# Bad - never do this
const apiKey = "your-key" // Hardcoded!

Limit key exposure

Never expose keys in client-side code (browser JavaScript, mobile apps)
Don’t share keys in Slack, email, or other channels
Make API calls from server-side code only

Use minimal permissions

Only grant the permissions your integration needs:

Analytics dashboard? stats: ["read"] only
Link creation tool? shortLinks: ["create"] only
Don’t grant delete unless necessary

Rotate keys regularly

Create new keys periodically (e.g., quarterly)
Revoke old keys after migrating to new ones
Immediately revoke any potentially compromised keys

Use separate keys per environment

Create distinct keys for:

Development
Staging
Production

This limits blast radius if a key is compromised and makes it easier to track usage.

Monitor usage

Review API usage in the dashboard
Watch for unexpected activity patterns
Set up webhooks for audit logging

Error handling

401 Unauthorized

Returned when authentication fails:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Common causes:

Missing x-api-key header
Typo in the API key
Key has been revoked
Using wrong header name (use x-api-key, not Authorization)

403 Forbidden

Returned when your key doesn’t have permission:

{
  "error": {
    "code": "ACTION_NOT_ALLOWED",
    "message": "Your API key doesn't have permission for this action"
  }
}

Common causes:

Key doesn’t have the required permission for this resource/action
Trying to access resources from another organization

Handling auth errors

async function makeRequest(endpoint, options = {}) {
  const response = await fetch(`https://api.h0p.co${endpoint}`, {
    ...options,
    headers: {
      'x-api-key': process.env.H0P_API_KEY,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  if (response.status === 401) {
    throw new Error('Invalid API key. Check your credentials.');
  }

  if (response.status === 403) {
    const error = await response.json();
    throw new Error(`Permission denied: ${error.error.message}`);
  }

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || 'Request failed');
  }

  return response.json();
}

Next steps

Quickstart

Make your first API call.

API introduction

Learn about all available endpoints.

Webhooks

Set up real-time notifications.

Contact support

Get help with authentication issues.

Getting Started

Endpoints

Authentication

API key overview

Key types

Creating an API key

Permissions

Available resources

Available actions

Example permission configurations

Using your API key

POST request example

Using environment variables

Managing API keys

View your keys

Update key permissions

Revoke a key

Security best practices

Error handling

401 Unauthorized

403 Forbidden

Handling auth errors

Next steps

Quickstart

API introduction

Webhooks

Contact support

Getting Started

Endpoints

​API key overview

​Key types

​Creating an API key

​Permissions

​Available resources

​Available actions

​Example permission configurations

​Using your API key

​POST request example

​Using environment variables

​Managing API keys

​View your keys

​Update key permissions

​Revoke a key

​Security best practices

​Error handling

​401 Unauthorized

​403 Forbidden

​Handling auth errors

​Next steps

Quickstart

API introduction

Webhooks

Contact support

API key overview

Key types

Creating an API key

Permissions

Available resources

Available actions

Example permission configurations

Using your API key

POST request example

Using environment variables

Managing API keys

View your keys

Update key permissions

Revoke a key

Security best practices

Error handling

401 Unauthorized

403 Forbidden

Handling auth errors

Next steps