Authentication

Getting an API Key

API access is currently by invitation. To request credentials, email thomas@thebuoy.app. Once your request is approved, you’ll receive an API key. Store it securely — it’s shown only once and cannot be retrieved later. If you lose it, we can generate a new one, which immediately invalidates the old one.

If your key is compromised, contact support to rotate it.

Using Your API Key

Include your API key in every request using the Authorization header:

Authorization: Bearer YOUR_API_KEY

Header authentication (recommended)

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.thebuoy.app/v2/buoys?country=FR"

Query parameter (alternative)

If you can’t set headers, pass the key as a query parameter:

curl "https://api.thebuoy.app/v2/buoys?country=FR&api_key=YOUR_API_KEY"

Prefer the Authorization header — query parameters appear in server logs and browser history.

Public Endpoints

Two endpoints do not require authentication and are available to anyone:

Endpoint	Description
`GET /api/v2/buoys/search`	Search buoys by name or identifier
`GET /api/v2/buoys/nearest`	Find the nearest buoy to coordinates

Authentication Errors

{
  "error": "unauthorized",
  "message": "API key required"
}

{
  "error": "unauthorized",
  "message": "Invalid API key"
}

Rate Limit Headers

Every authenticated response includes these headers so you can track your usage:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1735326000

Header	Description
`X-RateLimit-Limit`	Your hourly request quota
`X-RateLimit-Remaining`	Requests remaining this hour
`X-RateLimit-Reset`	Unix timestamp when the quota resets

When your quota is exceeded, the API returns 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded 1000 requests per hour",
  "retry_after": 1847,
  "reset_at": "2026-03-27T15:00:00Z"
}

See the Rate Limits guide for details on planning around quotas.

Getting Started

Use Cases

Getting an API Key

Using Your API Key

Header authentication (recommended)

Query parameter (alternative)

Public Endpoints

Authentication Errors

Rate Limit Headers

​Getting an API Key

​Using Your API Key

​Header authentication (recommended)

​Query parameter (alternative)

​Public Endpoints

​Authentication Errors

​Rate Limit Headers

Getting an API Key

Using Your API Key

Header authentication (recommended)

Query parameter (alternative)

Public Endpoints

Authentication Errors

Rate Limit Headers