Development

This guide covers the core developer concepts in H0p, including authentication, API access, and integration options. Whether you’re building an integration or automating your workflow, this page provides the foundation you need.

API key authentication

For programmatic access to H0p, use API keys. API keys provide:

Persistent access - No need to handle login flows
Granular permissions - Control exactly what each key can do
Organization scope - Keys are tied to a specific organization

Learn how to create and use API keys in the Authentication guide.

API key types

H0p supports two types of API keys:

User keys
Bot keys

User keys are linked to your personal account:

One key per user per organization
Actions are attributed to you in audit logs
Key is deleted if you leave the organization
Inherits your user permissions

Best for: Personal scripts, development, testing

Permission model

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

Resources

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

Actions

Each resource supports these actions:

create - Create new items
read - View existing items
update - Modify existing items
delete - Remove items

Example permissions

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

This key can fully manage short links, view domains and stats, and upload files.

Role-based access control

Organization members have roles that determine their default permissions:

Role	Short Links	Domains	API Keys	Webhooks	Stats
Owner	Full	Full	Full	Full	Read
Admin	Full	Full	Full	Full	Read
Member	Full	Create, Read, Update	None	None	Read

API keys can only have permissions equal to or less than the creating user’s role allows.

Integration options

H0p offers multiple ways to integrate with your systems:

REST API

Our primary integration method. Full CRUD operations for all resources.

Base URL: https://api.h0p.co
Authentication: API key in x-api-key header
Format: JSON request/response
Documentation: API Reference

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"}'

Webhooks

Receive real-time notifications for events in your organization. Available events:

link.created - New link created
link.updated - Link modified
link.deleted - Link removed
link.clicked - Someone clicked a link

Learn more about Webhooks.

MCP Server

The Model Context Protocol (MCP) enables AI tools to interact with H0p directly. Supported tools:

Claude Desktop
Claude Code (CLI)
Cursor
Windsurf
ChatGPT (via custom actions)

Learn more about MCP integration.

Rate limiting

API requests are rate limited to ensure fair usage:

Limit	Value
Requests per second	5
Requests per minute	100

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 60 seconds."
  }
}

Implement exponential backoff in your integration to handle rate limits gracefully.

Error handling

All API errors follow a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Common error codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource doesn’t exist
`ALREADY_EXIST`	409	Resource with that identifier exists
`PLAN_LIMIT_REACHED`	403	Plan limit exceeded
`FEATURE_NOT_AVAILABLE`	403	Premium feature on free plan
`VALIDATION_ERROR`	400	Invalid request data

Security best practices

Store keys securely

Never commit API keys to version control. Use environment variables or a secrets manager.

# Good: Environment variable
export H0P_API_KEY="your-api-key"

# Bad: Hardcoded in code
const apiKey = "your-api-key"  // Don't do this!

Use minimal permissions

Only grant the permissions your integration needs. A read-only integration shouldn’t have delete permissions.

Rotate keys regularly

Periodically create new keys and revoke old ones, especially after team changes.

Monitor usage

Review your API usage and webhook delivery logs for unexpected activity.

Next steps

API Quickstart

Make your first API call and create a link programmatically.

Authentication

Learn how to create and manage API keys.

Webhooks

Set up real-time notifications for your integration.

MCP Integration

Connect H0p to your AI development tools.

Getting Started

Features

Integrations

Development

API key authentication

API key types

Permission model

Resources

Actions

Example permissions

Role-based access control

Integration options

REST API

Webhooks

MCP Server

Rate limiting

Error handling

Common error codes

Security best practices

Next steps

API Quickstart

Authentication

Webhooks

MCP Integration

​API key authentication

​API key types

​Permission model

​Resources

​Actions

​Example permissions

​Role-based access control

​Integration options

​REST API

​Webhooks

​MCP Server

​Rate limiting

​Error handling

​Common error codes

​Security best practices

​Next steps

API Quickstart

Authentication

Webhooks

MCP Integration

API key authentication

API key types

Permission model

Resources

Actions

Example permissions

Role-based access control

Integration options

REST API

Webhooks

MCP Server

Rate limiting

Error handling

Common error codes

Security best practices

Next steps