Skip to main content
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 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

ResourceDescription
shortLinksCreate, read, update, delete short links
domainsManage custom domains
statsAccess analytics data
filesUpload and manage files (QR codes, images)
apiKeysManage API keys (admin only)
webhooksConfigure 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:
RoleShort LinksDomainsAPI KeysWebhooksStats
OwnerFullFullFullFullRead
AdminFullFullFullFullRead
MemberFullCreate, Read, UpdateNoneNoneRead
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:
LimitValue
Requests per second5
Requests per minute100
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

CodeHTTP StatusDescription
UNAUTHORIZED401Invalid or missing API key
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource doesn’t exist
ALREADY_EXIST409Resource with that identifier exists
PLAN_LIMIT_REACHED403Plan limit exceeded
FEATURE_NOT_AVAILABLE403Premium feature on free plan
VALIDATION_ERROR400Invalid request data

​
Security best practices

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!
Only grant the permissions your integration needs. A read-only integration shouldn’t have delete permissions.
Periodically create new keys and revoke old ones, especially after team changes.
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.