# Open Places API auth.md

Open Places API uses server-side bearer API keys. Do not embed a key in browser JavaScript, a public repository, logs, or an AI prompt.

## Agent registration and credential provisioning

This document is for server-side agents acting on behalf of a registered human user. Open Places API supports **human-mediated API key provisioning**; it does not support anonymous or autonomous agent registration.

- Registration endpoint: https://app.openplacesapi.com/signup
- Credential provisioning endpoint: https://app.openplacesapi.com/ (the API keys panel on the dashboard overview, after sign-in)
- Supported registration method: verified human account (Google or GitHub sign-in) with a server-side bearer API key
- Supported credential type: bearer API key

Provision access as follows:

1. A human user creates an account at https://app.openplacesapi.com/signup with a Google or GitHub account, and verifies their email address if the provider has not already verified it.
2. The user creates an API key in the dashboard.
3. The full key is shown only when it is created. Store it in a server-side secret manager.

Automated agents must not create accounts or keys without the user's explicit participation. A human may provide a key to a trusted server-side agent, and can revoke that key in the dashboard at any time.

## Authenticate API requests

Send the key in the Authorization header:

```http
Authorization: Bearer opa_live_...
```

Example endpoint:

```http
GET https://api.openplacesapi.com/v1/places?q=coffee&lat=40.7128&lon=-74.0060
Authorization: Bearer opa_live_...
```

A `q` that names a kind of place, such as `pharmacy`, also searches that category; `meta.interpreted_as` explains the reading, and `mode=name` searches names literally.

Category lookup does not need a key: `GET https://api.openplacesapi.com/v1/categories?q=<text>` returns valid category slugs.

## Errors

Error bodies include `code`, `message`, `request_id`, and `docs_url`. A missing key returns `401 unauthenticated`; a malformed, revoked, or unknown key returns `401 invalid_api_key`. Do not retry either with the same credentials; ask the user for a valid key.

## MCP server

The hosted MCP endpoint is https://app.openplacesapi.com/mcp and accepts the same bearer key in the Authorization header. It exposes `search_places` and `list_categories`.

## More information

- Documentation: https://openplacesapi.com/docs
- OpenAPI contract: https://openplacesapi.com/openapi.yaml
- Error and quota behavior: https://openplacesapi.com/docs/errors