# Authentication: Mind Polling API

**Finding and reading public polls and their latest results needs no key.** Every raw answer, results as of a past moment, the change feed and everything about your own polls need a key, made by the account holder at https://mindpolling.com/app/settings/api. A key with only the read scope is free and spends nothing. An agent cannot make a key or an account for itself: a key can spend the account's money, so it is the account holder's choice.

## Sending a key

`Authorization: Bearer mp_live_...` (or `X-API-Key: mp_live_...`). Keys are `mp_live_` or `mp_test_` and 46 characters, ending in a checksum, so a mistyped key is refused before it is looked up. Check one with `GET https://mindpolling.com/api/v1/me`, which also lists what the key cannot do and why.

## Scopes

- **read**: your private polls, their results, runs, answers, changes and webhooks.
- **write**: create, change and pause polls. Costs nothing.
- **run**: start polls and run them now. Spends the balance.

A live key with run must have a monthly allowance, the most it may commit in a calendar month (UTC). A call that would pass it is refused (409 `allowance_spent`), and a scheduled run that would pass it is skipped and its poll paused until the allowance is raised.

## Spending

Every call that spends carries `max_cost_usd`, the most it may commit; without it, or with too little, it is refused and the answer says the exact amount. `estimate_poll` gives the figures first. An empty balance is a 402 with the shortfall and the page where the account holder adds funds.

## Test keys

`mp_test_` keys work on test polls only, which they create. A test run answers from a stub model, charges nothing, needs no `max_cost_usd`, and never appears in public or in the account holder's list.

## When a key does not work

| Answer | Code | Meaning |
|---|---|---|
| 401 | key_required | No key was sent. |
| 401 | key_invalid | Not one of our keys, mistyped, or replaced by a rotation. |
| 401 | key_revoked, key_expired | It was revoked, or it expired. |
| 403 | scope_missing | The key lacks the scope this needs. |
| 429 | too_many_bad_keys | Too many failing keys from one address; wait for Retry-After. |
| 503 | unavailable | Keys cannot be checked right now. Your key is fine: do not make a new one. |

## What is logged

Every request is logged for 30 days: the key (or none), the operation, the poll, the status, the time taken, REST or MCP, and the user agent. No address is kept. The account holder sees each key's request count on the API keys page.

## Rotating and revoking

`POST https://mindpolling.com/api/v1/me/key/rotate` gives the key a new secret (shown once) and stops the old one at once; scopes and allowance stay. `DELETE https://mindpolling.com/api/v1/me/key` revokes it for good.

## Every operation

| Operation | Method and path | Needs |
|---|---|---|
| get_me | GET /api/v1/me | a key |
| list_polls | GET /api/v1/polls | nothing for public polls; read for your own |
| get_poll | GET /api/v1/polls/{id} | nothing for public polls; read for your own |
| get_results | GET /api/v1/polls/{id}/results | nothing for public polls; read for your own |
| list_runs | GET /api/v1/polls/{id}/runs | nothing for public polls; read for your own |
| list_calls | GET /api/v1/polls/{id}/calls | a key with read |
| list_models | GET /api/v1/models | nothing |
| search_places | GET /api/v1/places | a key with read |
| get_place | GET /api/v1/places/{id} | a key with read |
| rotate_key | POST /api/v1/me/key/rotate | a key |
| revoke_key | DELETE /api/v1/me/key | a key |
| create_poll | POST /api/v1/polls | a key with write |
| update_poll | PUT /api/v1/polls/{id} | a key with write |
| estimate_poll | GET /api/v1/polls/{id}/estimate | a key with read |
| start_poll | POST /api/v1/polls/{id}/start | a key with run |
| run_poll_now | POST /api/v1/polls/{id}/run | a key with run |
| pause_poll | POST /api/v1/polls/{id}/pause | a key with write |
| get_live_run | GET /api/v1/polls/{id}/status | a key with read |
| list_changes | GET /api/v1/changes | a key with read |
| create_webhook | POST /api/v1/webhooks | a key with read |
| list_webhooks | GET /api/v1/webhooks | a key with read |
| delete_webhook | DELETE /api/v1/webhooks/{id} | a key with read |
