Skip to main content

Overview

Most 9Pic API integrations authenticate with a long-lived API key sent in the X-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 the X-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.
The full API key is shown only once at creation time. There is no recovery flow.
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:
Unlike an API key, the token belongs to a person, not an organisation. It can reach every organisation where that person is a team member, and access is re-checked on every request, so removing someone from a team takes effect immediately.
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 keeps X-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.