Overview
Most 9Pic API integrations authenticate with a long-lived API key sent in theX-API-Key header. Keys are scoped to one organisation and validated on every request, along with the calling host and the URL’s org_id / event_id.
The organiser photo workflow also accepts an OAuth access token, issued when a 9Pic user connects the 9Pic AI app in a supported AI assistant. Send one credential per request, never both.
Sending the API Key
Add theX-API-Key header to every request:
Creating an API Key
1
Open Developer Zone
Sign in to admin.9pic.ai and open the Developer Zone page from the left sidebar.
2
Create a new token
Click Create Token, then confirm in the dialog. The new key is generated server-side and added to your token list.
3
Copy your token
The full key is displayed only once. Click Copy and store it in your secret manager. If you lose it, you must delete the old token and create a new one.
Developer Zone is open on Business, Custom, Enterprise and during Trial. Pay As You Go and Pro organisations can’t create API keys.
Each organisation can have up to 10 API tokens. You can deactivate or delete tokens at any time from the Developer Zone page.
Managing Tokens
From the Developer Zone page you can:- Activate / Deactivate a token using the toggle. Deactivated tokens are immediately rejected.
- Delete a token permanently. Any service using that token loses access on the next request.
What Gets Validated
Every API call goes through these checks:
A missing key returns
401, an unknown event_id returns 404, and any other failure returns 403. See Errors for the full list of 403 causes.
OAuth Access Tokens
When a 9Pic user connects the 9Pic AI app in a supported AI assistant (such as ChatGPT, Codex, or Claude Code), they sign in with their 9Pic account and approve the requested permissions. The assistant then calls the API on that user’s behalf with a short-lived OAuth access token:OAuth sign-in is available only to AI assistants approved by 9Pic. For your own server-to-server integration, use an API key.
Scopes
Endpoints That Accept OAuth
Every endpoint outside this table accepts
X-API-Key only and rejects bearer tokens. Existing API-key pipeline requests retain their original body and response contracts. OAuth writes require accepted organiser admin membership and an idempotency_key; only photo processing, which spends credits, needs a reviewed preview and confirmation. See Operations. This external analytics endpoint needs a plan with engagement analytics (Pro, Business, Custom or Enterprise).
What Gets Validated
A failed token check returns
401 with a WWW-Authenticate: Bearer error="invalid_token" header. Ask the user to reconnect the app. The other checks return 403.
Error Responses
See Errors for canonical descriptions and retry guidance.
Coding Agents
If a coding agent is writing the integration, install Agent Skills. The API skill keepsX-API-Key on your backend.
Agent Skills
Install skills for Cursor, Claude Code, Codex, and similar tools.
9Pic Integration skill
API keys, guest search galleries, clips, and selling originals.

