Authentication

One header for a program, a bearer token for a person or an agent, and 11 operations that need neither.

Public

No credential. Service discovery, the vocabularies and the OAuth metadata a client reads before it has a token.

API key

X-API-Key, or a bearer token. These accept either, so one client can serve a program and a person.

Bearer only

Acting as a person rather than as the organization, so a key that belongs to no one will not do.

Sending your key

Send your key in the X-API-Key header. Never put it in a query string, where it would land in logs, referrers and browser history.

curl 'http://localhost:8000/rule?address=100+Main+St' \
  -H 'X-API-Key: $PLACESTACK_API_KEY'

Create one key per deployment rather than one per organization, so revoking the one that leaked does not stop everything else you run. Keys belong to the organization, so they survive the person who created them leaving.

Get an API key

Security schemes

HTTPBearer: http (bearer)
APIKeyHeader: apiKey in header: X-API-Key

Every operation in the reference carries a Public or API key mark, so you can see what a call needs without reading this page twice.

Public operations

POST /sessionCreate Session
POST /organizationCreate Organization
POST /verificationCreate Verification
POST /password-resetCreate Password Reset
PUT /passwordSet Password
POST /membershipCreate Membership
GET /oauth/authorizeAuthorize
POST /oauth/tokenToken
GET /planThe plans on offer
GET /Identify the service
GET /healthCheck the service's health

Credential errors

A 401 means the credential is missing or unusable: check the header. A 403 with entitlement_missing means the key is fine but your plan does not cover the operation, so upgrading is the fix rather than retrying. A 402 means you are out of credit: the balance is prepaid and cannot go below zero, so top it up rather than retrying.

Every error code The OAuth flow an agent uses instead

Errors

The refusal shape, the status codes and every error code.