Authentication
Authenticate requests across the REST API, CLI, and MCP server with API keys.
Bearer token
All API requests must include your API key in the Authorization header:
curl https://shorten.dev/api/v1/links \
-H "Authorization: Bearer sk_your_key_here"Requests without a valid key return 401 Unauthorized.
API key scopes
Each API key is granted a set of scopes that control what operations it can perform.
| Scope | Permissions |
|---|---|
read | List links, get link details, view analytics |
write | Create and revoke links |
admin | Full access — includes all permissions and admin endpoints |
The admin scope includes all permissions and must be the only scope on a key — it cannot be combined with read or write. Fine-grained scopes (read, write) can be combined freely.
Recommended scope combinations
| Integration | Recommended scopes |
|---|---|
| Read-only access | read |
| Link management | read, write |
| CI/CD pipeline | admin |
Key management
Create keys from the API Keys dashboard. You can have up to 20 active keys per account. The full key is shown once at creation — store it securely.
If a key is compromised, delete it immediately from the dashboard. Deletion is instant and permanent.
Security best practices
- Never expose keys in client-side code — API keys should only be used server-side or in secure environments.
- Rotate keys periodically — Delete old keys and create new ones from the dashboard.
- Use environment variables — Store keys in
SHORTEN_API_KEYrather than hardcoding them. - Scope minimally — Only grant the permissions your integration needs.