Authentication

Every request to apis.cloud.feeef.org carries a bearer credential — an API key or an OAuth access token. API requests use bearer authentication. Keep long-lived keys on your server; do not embed them in public client code. The trusted Cloud playground holds a pasted credential only in memory.

Authorization: Bearer fc_live_3v9…            # API key
Authorization: Bearer <oauth access token>    # OAuth app acting for a user

API keys

Keys are project-scoped — every resource an authenticated request touches belongs to the key's project, never another one. Create and revoke them from API keys.

Scopes

Scope	Grants
`geo:read`	Catalog, polygons, pickups, search, nearby, reverse
`geo:resolve`	Address matching, single and batch

Choose explicit scopes for each credential. AI reads need ai:read; paid generation needs ai:generate. Tenant administration uses tenants:manage and webhook administration uses webhooks:manage.

Product must be enabled too

A scope is necessary but not sufficient. If the project has not enabled the product, every request to it returns 403 product_not_enabled regardless of scope. See API catalog.

OAuth2 — acting on behalf of a user

Register an app under OAuth apps when your integration needs to act as someone else's project, not your own — the standard authorization-code flow, PKCE mandatory for public clients (mobile apps and SPAs, which cannot hold a secret).

GET /oauth/authorize
  ?client_id=…
  &redirect_uri=…
  &response_type=code
  &scope=parcels:read+parcels:write
  &state=…
  &code_challenge=…
  &code_challenge_method=S256

The user is redirected to the console's consent screen, approves the listed scopes, and your redirect URI receives a code. Exchange it:

POST /oauth/token

Grants: authorization_code (+ PKCE) and refresh_token. Returns an access_token (bearer, 90-day lifetime), a rotating refresh_token, the granted scope, and expires_in.

An OAuth token is accepted anywhere an API key is — with one difference: the effective project is the user's, not the app's, and endpoints requiring project ownership check that user's membership.

POST /oauth/revoke (RFC 7009) and POST /oauth/introspect (RFC 7662) are both implemented.

Errors

HTTP	code	meaning
401	`invalid_api_key` / `invalid_token`	unknown, revoked, or expired credential
403	`insufficient_scope`	credential lacks the required scope (`WWW-Authenticate` set)
403	`product_not_enabled`	project has not enabled this product

See Conventions for the full error envelope and every other response header.

API keys

Scopes

OAuth2 — acting on behalf of a user

Errors

On this page