Authentication

Every request to the PhotoPick API must include a Bearer token in the Authorization header.

GET /api/v1/me HTTP/1.1
Host: api.photopick.cz
Authorization: Bearer pp_live_xxxxxxxxxxxxxxxx

Keys are issued in Settings → API keys inside the PhotoPick app. Each key belongs to one customer account.

Key format

Prefix	Meaning
pp_live_	Production key. Acts against real data.
pp_test_	Reserved for future sandbox environments. Not issued today.

The full token is shown once at creation. PhotoPick stores only a hash — lost keys cannot be recovered, only rotated.

Scopes

A key is granted one or more scopes at creation time. Scopes are not editable after the fact; to change them, create a new key.

Scope	Grants
customer:read	GET /me, GET /customer
photos:read	GET /photos, GET /photos/{id}, GET /photos/{id}/download, GET /photos/{id}/tags
photos:write	PATCH /photos/{id}, PUT /photos/{id}/tags
photos:delete	DELETE /photos/{id}
tags:read	GET /tags, GET /tags/{id}
tags:write	POST /tags, PATCH /tags/{id}, DELETE /tags/{id}

A request that hits an endpoint your key is not scoped for returns 403 with code: "scope_required" and the missing scope name in details.scope.

IP whitelist (optional)

Each key can be locked to a set of IPv4 and IPv6 addresses or CIDR ranges. When set, requests from any other source IP return 403 with code: "ip_not_whitelisted" — regardless of the key being otherwise valid.

This is configured per-key in Settings → API keys → Edit. Leave the list empty to accept any source IP.

Behind a proxy?

The whitelist matches the public IP that hits PhotoPick’s edge. If your traffic egresses through a load balancer, NAT, or proxy, whitelist the proxy’s IP — not your internal one.

Failure responses

HTTP	code	Cause
401	unauthorized	Missing, malformed, or unknown key.
403	scope_required	Key is valid but lacks the scope the endpoint demands.
403	ip_not_whitelisted	Source IP not in the key’s whitelist.
429	rate_limited	Too many requests. See Rate limits.

See Errors for the full envelope shape.

Rotating keys

1. Create a new key with the same scopes.
2. Deploy the new key to your integration.
3. Delete the old key in Settings → API keys.

Deletion takes effect immediately — there is no grace period. Plan deploys accordingly.