Authentication

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

Authorization: Bearer sk_live_your_key_here

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.

Minting a key

Create a v2 API key in 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:

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.

curl https://api.pickfu.com/v2/me \
  -H "Authorization: Bearer sk_live_your_key_here"

{
  "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.

API Reference

API v2

Surveys

Responses

Tags

Traits

Playbooks

Projects

Media

Authentication

Minting a key

Scopes

Older unscoped keys

Identifying the team (optional)

Who’s calling? `GET /v2/me`

​Minting a key

​Scopes

​Older unscoped keys

​Identifying the team (optional)

​Who’s calling? GET /v2/me

Minting a key

Scopes

Older unscoped keys

Identifying the team (optional)

Who’s calling? `GET /v2/me`