> ## Documentation Index
> Fetch the complete documentation index at: https://docs.h0p.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Development
> Key concepts for developers building with H0p
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-reference/authentication).
## 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
**Bot keys** create non-human accounts associated with API keys:
* One bot key per organization
* Creates a dedicated bot user not tied to any individual
* Doesn't count toward your organization's member limit
* Survives team member changes and turnover
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.
## 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
```json theme={null}
{
"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](/api-reference/introduction)
```bash theme={null}
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](/platform/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](/platform/mcp).
## 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.
```json theme={null}
{
"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:
```json theme={null}
{
"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
Never commit API keys to version control. Use environment variables or a secrets manager.
```bash theme={null}
# 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
Make your first API call and create a link programmatically.
Learn how to create and manage API keys.
Set up real-time notifications for your integration.
Connect H0p to your AI development tools.