# auth.md

Overspan is a paid, hosted OpenStreetMap Overpass API at `https://api.overspan.dev`.
This document tells an autonomous agent, or the developer building one, how to obtain
a credential and how to use it.

Last updated 2026-08-13.

## Who this is for

Machine clients that need raw OSM query access. There is no free tier, no anonymous
access, and no trial key. Every request is authenticated and metered.

## Credential model

One opaque API key per subscription. No user accounts, no OAuth, no token exchange,
no scopes. The key is issued by our billing provider (Lemon Squeezy) at purchase and
is the only credential the API accepts.

Overspan publishes no OAuth Protected Resource Metadata and no Authorization Server
metadata, because it operates neither. If that changes, this document changes with it.

## Getting a key

Registration is a purchase, and it is not automated. A human with a payment method
completes checkout at <https://overspan.dev/#pricing>, and the key arrives in the
order email.

There is no registration endpoint, no dynamic client registration, and no self-service
provisioning. An agent that needs a key must ask its operator for one. Do not probe for
a registration path: there isn't one.

Questions before buying: <https://overspan.dev/contact> or hello@overspan.dev

## Using the key

Preferred, and the only form that keeps the key out of logs and browser history:

```
Authorization: Bearer YOUR_KEY
```

Also accepted, for clients that only let you set a base URL (JOSM, overpass-turbo,
osmnx):

```
https://api.overspan.dev/YOUR_KEY/api/interpreter
https://api.overspan.dev/api/interpreter?key=YOUR_KEY
```

Both of those put the key in the URL, where it lands in server logs and referrer
chains. Use the header unless your client cannot send one.

The same three forms work on `/api/usage`.

## What the API tells you back

- Every response carries `X-Overspan-Quota-Limit`, `X-Overspan-Quota-Remaining`, and
  `X-Overspan-Quota-Reset`.
- `401` (`invalid_key`, or `missing_key` when no key was sent at all) means the key is
  absent, unknown, or inactive. Retrying will not fix it.
- `429` means a monthly quota, per-minute rate, or concurrency limit was reached
  (`quota_exceeded`, `rate_limited`, `concurrency_limit`). `Retry-After` is set on all
  three.
- `GET /api/usage` returns the key's tier, its limits, and its usage history. It reads
  the metering database only, never consumes query quota, and does not depend on a
  healthy Overpass backend.

Limits per tier, the full error list, and the exact request and response shapes are in
<https://overspan.dev/openapi.json> and <https://overspan.dev/docs/>.

## Rotation and revocation

Manage or cancel a subscription at <https://store.overspan.dev/billing> (email magic
link, no password). Cancellation revokes the key. To rotate a key, or if one is
exposed, email hello@overspan.dev.

Terms: <https://overspan.dev/terms> · Privacy: <https://overspan.dev/privacy>