API Keys

Overview

API keys provide programmatic access to the Spoo.me API without requiring interactive authentication. They allow you to automate URL shortening, retrieve analytics, and manage your URLs from scripts, applications, and integrations.

API keys are only available in API v1. The legacy v0 API does not support API key authentication.

Authentication Methods

Spoo.me v1 API supports three authentication methods:

Anonymous

No authentication required

Lower rate limits
Cannot manage URLs later
Limited features

JWT Token

Interactive user sessions

Full dashboard access
Manage URLs via web UI
Highest privileges

API Key

Programmatic access

Scoped permissions
Long-lived tokens
Perfect for automation

API Key Scopes

API keys can be granted specific permissions (scopes) to limit their access:

Scope	Description	Endpoints
`shorten:create`	Create new shortened URLs	`POST /api/v1/shorten`
`urls:read`	View URL details and list	`GET /api/v1/urls`
`urls:manage`	Update and delete URLs	`PATCH/DELETE /api/v1/urls/*`
`stats:read`	Access analytics data	`GET /api/v1/stats`
`admin:all`	Full administrative access	All endpoints

Principle of Least Privilege: Only grant the minimum scopes needed for your use case. For example, if you only need to shorten URLs, use shorten:create instead of admin:all.

Creating API Keys

Via Web Dashboard

Log in to your Spoo.me Dashboard
Navigate to Settings → API Keys
Click Create New API Key
Configure your key:
- Name: Human-readable identifier (e.g., “Production Server”)
- Description: Optional details about key’s purpose
- Scopes: Select required permissions
- Expiration: Optional expiration date
Click Create
Copy the key immediately - it won’t be shown again!

One-Time Display: The full API key is shown only once at creation. Store it securely immediately. If you lose it, you’ll need to create a new key.

Using API Keys

API keys must be sent in the Authorization header with the Bearer scheme:

Authorization: Bearer YOUR_API_KEY_HERE

Example: Shorten a URL

curl -X POST https://spoo.me/api/v1/shorten \
  -H "Authorization: Bearer spoo_AbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com/very/long/url",
    "alias": "mylink"
  }'

Example: Get Statistics

curl -X GET "https://spoo.me/api/v1/stats?scope=all" \
  -H "Authorization: Bearer spoo_AbCdEfGhIjKlMnOpQrStUvWxYz"

Example: List Your URLs

curl -X GET "https://spoo.me/api/v1/urls?page=1&pageSize=20" \
  -H "Authorization: Bearer spoo_AbCdEfGhIjKlMnOpQrStUvWxYz"

Rate Limits with API Keys

API keys grant authenticated rate limits, which are significantly higher than anonymous limits:

With API Key

60 requests/minute
5000 requests/day
Access to management endpoints
Private stats support

Without API Key

20 requests/minute
1000 requests/day
Cannot manage URLs
Public URLs only

Security Best Practices

Store Keys Securely

Use environment variables, not hardcoded values
Never commit keys to version control
Use .gitignore to exclude files containing keys

Use Minimal Scopes

Grant only the permissions needed
Create separate keys for different purposes
Use shorten:create for simple automation, not admin:all

Rotate Keys Regularly

Set expiration dates on keys
Rotate keys every 90-180 days
Revoke old keys after rotation

Key Limits

Maximum Active Keys

20 keys per userOnly non-revoked keys count toward this limit.

Creation Rate Limit

5 keys per hourPrevents abuse and key spam.

Troubleshooting

401 Unauthorized - Invalid token

Possible causes:

API key was revoked or deleted
API key has expired
Incorrect key format (must start with spoo_)
Missing Authorization header

Solution: Verify the key is active and correctly formatted.

403 Forbidden - Insufficient permissions

Possible causes:

API key missing required scope
Trying to access someone else’s resources

Solution: Check that your key has the required scopes for the endpoint.

429 Too Many Requests - Rate limit exceeded

Possible causes:

Exceeded 60 requests per minute
Exceeded 5000 requests per day
Key creation limit (5 per hour)

Solution: Implement exponential backoff, cache results, or upgrade your rate limits.

Key not showing full token

Cause: Security feature - tokens are only shown once at creation.Solution: Create a new API key if you lost the original.

Getting Started

API v1 Reference

API v0 Reference (Legacy)

Tools & Libraries

Self Hosting

Overview

Authentication Methods

Anonymous

JWT Token

API Key

API Key Scopes

Creating API Keys

Via Web Dashboard

Using API Keys

Example: Shorten a URL

Example: Get Statistics

Example: List Your URLs

Rate Limits with API Keys

With API Key

Without API Key

Security Best Practices

Key Limits

Maximum Active Keys

Creation Rate Limit

Troubleshooting

API Key Lifecycle

Next Steps

API Reference

Rate Limits

Quick Start

Python Library

Getting Started

API v1 Reference

API v0 Reference (Legacy)

Tools & Libraries

Self Hosting

​Overview

​Authentication Methods

Anonymous

JWT Token

API Key

​API Key Scopes

​Creating API Keys

​Via Web Dashboard

​Using API Keys

​Example: Shorten a URL

​Example: Get Statistics

​Example: List Your URLs

​Rate Limits with API Keys

With API Key

Without API Key

​Security Best Practices

​Key Limits

Maximum Active Keys

Creation Rate Limit

​Troubleshooting

​API Key Lifecycle

​Next Steps

API Reference

Rate Limits

Quick Start

Python Library

Overview

Authentication Methods

API Key Scopes

Creating API Keys

Via Web Dashboard

Using API Keys

Example: Shorten a URL

Example: Get Statistics

Example: List Your URLs

Rate Limits with API Keys

Security Best Practices

Key Limits

Troubleshooting

API Key Lifecycle

Next Steps