Authentication

API Documentation

Plung uses API key authentication for all developer API access.

v2 API: API Key Authentication

The v2 API requires authentication via API keys. Each request must include an Authorization header with a Bearer token containing your API key. Rate limits are enforced per API key and depend on plan: 60 to 5,000 requests per 60 seconds per key.

API keys are available on all plans, including the free FREE tier. You can manage your API keys and upgrade your plan in the Developer Console. Different pricing tiers offer higher rate limits and monthly request volumes.

Plan	Rate Limit	Monthly API Calls
FREE	60/min	2,000
HOBBY	300/min	25,000
INDIE	1,000/min	150,000
PRO	5,000/min	500,000

Using API Keys

Include your API key as a Bearer token in the Authorization header with every v2 API request:

bash

curl -X POST https://api.plung.co/v2/shorten \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{"url": "https://example.com"}'

Authentication Errors

v2 endpoints return 401 Unauthorized when authentication fails. The response includes a specific error message:

Missing API key:

json

{
  "statusCode": 401,
  "message": "API key required. Pass your key as: Authorization: Bearer <your-key>",
  "error": "Unauthorized"
}

Invalid API key:

json

{
  "statusCode": 401,
  "message": "Invalid or inactive API key.",
  "error": "Unauthorized"
}

Rate limit exceeded:

json

{
  "statusCode": 429,
  "message": "Rate limit exceeded. Try again in the next minute."
}

Rate Limiting

All v2 API responses include rate limit headers that indicate your current usage:

Parameter	Type	Required	Description
X-RateLimit-Limit	number	Required	Maximum number of requests allowed per 60-second window for your plan (60 FREE, 300 HOBBY, 1,000 INDIE, 5,000 PRO).
X-RateLimit-Remaining	number	Required	Number of requests remaining in the current 60-second window.
X-RateLimit-Reset	number	Required	Unix timestamp (seconds) when the rate limit window resets.
X-API-Key-Name	string	Required	Human-readable name of the API key used for the request.

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

json

{
  "statusCode": 429,
  "message": "Rate limit exceeded. Try again in the next minute."
}

For detailed rate limit information, see the Rate Limiting section.

PreviousGetting Started NextRate Limiting