> ## Documentation Index
> Fetch the complete documentation index at: https://www.pickfu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to mint a v2 API key, pick its scopes, and identify your team on every request.

The v2 API accepts **API keys only** (`sk_live_…`). Every request carries the key as a Bearer token:

```bash theme={null}
Authorization: Bearer sk_live_your_key_here
```

<Note>
  OAuth 2.0 access tokens are **not** accepted on `/v2`. OAuth is a v1 surface and stays on `/v1`. If you're building a partner app that acts on behalf of individual PickFu users interactively, use v1 with OAuth.
</Note>

## Minting a key

Create a v2 API key in [Settings → API keys](https://app.pickfu.com/settings/api-keys). A key belongs to exactly **one team** and is the unit of authorization — every resource the key can see or change belongs to that team.

The create form has a **scopes** picker with all three scopes checked by default. Uncheck any scope the key doesn't need; leave them all checked to mint an all-scopes key. Each existing key's scopes are shown on the list; keys with no scopes are flagged as **not working with v2** and need to be re-issued.

## Scopes

Every v2 key carries an explicit subset of three scopes.

| Scope | What it grants |
| - | - |
| `read` | List and read team resources: `GET /v2/me`, `/v2/surveys`, `/v2/traits`, `/v2/orders`, `/v2/credit-balance`, `/v2/webhook-endpoints`, responses, CSV exports. |
| `write` | Draft and edit resources without spending money: `POST/PATCH /v2/surveys`, `POST /v2/surveys/{id}/stop`, `POST /v2/media`, all `/v2/webhook-endpoints` writes. |
| `spend` | Money-moving actions: `POST /v2/surveys/{id}/publish`, `POST /v2/orders`, `POST /v2/billing-portal-sessions`. |

A key with **no scopes** is rejected on every v2 route with `403 api_key_unscoped`. Re-issue the key in Settings to fix it — pick the scopes you want, or leave all three checked.

Publishing a survey needs `spend`; a `write`-only key can draft and edit surveys but cannot spend money on them. A `read`-only key can watch progress and download results.

### Older unscoped keys

Keys minted before the scope picker landed had **no scopes** attached, so they now fail every v2 call with `403 api_key_unscoped`. Those keys keep working on v1. To use v2, mint a new key with the scopes you need — the create form now defaults to all three scopes, so a key minted without touching the picker will accept every v2 call the caller is otherwise entitled to.

## Identifying the team (optional)

The team is the key. You can optionally assert which team you *think* you're calling by sending:

```bash theme={null}
X-PickFu-Team: tm_your_team_id
```

If the header is present and doesn't match the key's team, the request fails `403 team_mismatch`. Use this as a defensive check in multi-tenant integrations where a key is loaded by ID and you want to guarantee the caller and the key agree on the team.

## Who's calling? `GET /v2/me`

`GET /v2/me` returns the calling key, the team it acts for, and (when known) the user who minted it.

```bash theme={null}
curl https://api.pickfu.com/v2/me \
  -H "Authorization: Bearer sk_live_your_key_here"
```

```json theme={null}
{
  "object": "me",
  "team": {
    "object": "team",
    "id": "tm_01J9C2VZH8...",
    "name": "Acme Research"
  },
  "user": {
    "object": "user",
    "id": "usr_01J9C2VZH8...",
    "email": "founder@acme.example",
    "name": "founder"
  },
  "apiKey": {
    "object": "api_key",
    "name": "Production key",
    "scopes": ["read", "write", "spend"],
    "livemode": true
  }
}
```

`livemode` is `true` for `sk_live_…` keys.


## Related topics

- [PickFu MCP server for Claude, Cursor, and ChatGPT](/docs/integrations/mcp-server.md)
- [PickFu REST API reference and conventions](/docs/api-reference/introduction.md)
- [Why was my card declined at checkout?](/help/why-was-my-card-declined-at-checkout.md)
- [Publishing and payments](/docs/api-reference/v2/payments.md)
- [What integrations are available with PickFu?](/help/what-integrations-are-available-with-pickfu.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.