Test keys and live keys, what each permission opens, how long a key lasts, and how to check a key.
An API key (a secret password your server sends with every request) tells PCIFIC who you are and what you may do. Your server sends it in the Authorization header. It never goes in a browser page, a mobile app or a code repository.
Authorization: Bearer pcific_test_your_key_here| Key | Starts with | What it can call | Credits | Use it for |
|---|---|---|---|---|
| Test | pcific_test_ | The real tools, with real answers. Only what the permissions on the key allow. | Spends no credits. Test keys share an AI request cap for each shop: PCIFIC's ceiling is 200 per shop per UTC day by default, or your lower saved cap. | Building and testing, and the only key that may change tool settings and listing fields. |
| Live | pcific_live_ | The real tools. It can read settings and listing fields but never change them. | Spends credits when a tool does its work. Your spending limits and balance apply. | Production, on your server. Choose Live key and press Activate live key on the API keys page. |
Both kinds call the same web address, https://business.pcific.ai/api/v1. The start of the key decides which one you are using. The two never see each other's work: Orbit listings and photos, Safeguard reviews, Ask PCIFIC chats and unanswered questions and PixelTrace groups made with a test key can only be read, answered, retried or cancelled with a test key, and the same for live keys. Public certificate lookups by code stay public. Your settings, listing fields and documents are shared by both.
PCIFIC approves your account before you can make keys. Approved company email domains and accepted team invitations skip the wait. Account approval is the only approval from PCIFIC. To go live, choose Live key on the API keys page and press Activate live key; live calls spend credits bought from PCIFIC. Staff can suspend and restore live-key access (LIVE_KEYS_OFF).
A coding agent can get a test key without ever seeing it by using plain curl steps that you approve in your dashboard. They are in Getting started.
The agent starts a key link with POST /api/key-link and {suggestedName, destination, scopes}. scopes is an optional non-empty list of requested permission names: orbit, safeguard, ask-pcific, pixel-trace, settings, listing-fields, documents, webhooks, read, logs. For example, ["settings", "listing-fields", "documents", "read"] asks to set up an integration. The link stores these choices and the approval page pre-ticks them, with a plain label and explanation for each. The human can untick any permission before generating the key. Omitting scopes keeps the usual starting permissions. An empty list, null, a value that is not a list, an unknown or unavailable permission name is refused with 400 INVALID_FIELD, the place in /scopes and the valid names to send next.
A permission says which part of the API one key may use. A test key has only the permissions you tick. A live key can use the tools and read shared setup. It cannot change tool settings, listing fields or webhook endpoints.
| Permission | Shown in the dashboard as | What it opens |
|---|---|---|
orbit | Write listings with Orbit | Start listings, answer their questions, retry or cancel them, and upload photos. |
safeguard | Check listings with Safeguard | Start reviews, send seller answers, retry them, and upload photos. |
ask-pcific | Answer buyer questions with Ask PCIFIC | Ask questions and read the questions nothing answered. |
pixel-trace | Take and check photos with PixelTrace | Start photo groups, publish or retract them, and check photos. |
settings | Change tool settings | Read and change each tool's settings, the item lookup, the certificate label and spending limits, and add, rename or delete shops. Each call changes only the shop it names; a key for one shop cannot add or delete shops. |
listing-fields | Set up listing fields | Upload, publish and read your listing fields. |
documents | Manage Ask PCIFIC documents | Add, replace, refresh and delete documents. Changes waiting for approval are approved on the Documents page. |
webhooks | Manage webhook endpoints | Manage endpoints for test events, rotate their signing secrets, send test deliveries, and read their delivery logs. Use Webhooks on the dashboard to manage live endpoints. |
read | Read | Read results, settings, documents and listing fields. Logs needs its own logs permission. Other ticked permissions can also allow changes. |
logs | Read request logs | Read and export your business’s request logs. Locked and customer-held contents stay locked. Off unless you choose it. |
A new test key starts with orbit, safeguard, ask-pcific, pixel-trace, read. Settings, listing-fields, documents and webhooks are left unticked, because they change things your live site also uses. Tick them only on the key you use to set things up. Logs is also left unticked because it opens private request records.
The logs permission is off by default for test and live keys. Explicitly choose Read request logs when creating or editing a key, or send scopes: ["logs"] in key creation. A live key keeps its normal tool permissions. The read permission opens GET addresses except logs, so a key with only read can look at results, settings, documents and listing fields, and change nothing. GET /api/v1/key and GET /api/v1/me are open to every key whatever its permissions. /me includes business (id and name), marketplace (the limited shop, or null), kind, name, scopes and expiresAt. Neither returns the secret or its hash.
A test key needs the webhooks permission to add, edit, remove or test endpoints, or rotate secrets. It can only act on test endpoints (test: true), including secret rotation, test delivery, deletion and delivery logs. The list may show live metadata without secrets. Use Webhooks on the dashboard to manage live endpoints. Live keys may only read endpoints and delivery logs. The Webhooks guide explains test and live subscriptions and signature checks.
Every key has a lifetime you choose when you make it: 30, 60 or 90 days, any whole number of days from 1 to 365, or no end date. 60 days is the recommended choice. A key stops working on its date, whatever the traffic, and the dashboard marks it as expiring soon. A key with no end date works until you cancel it, so a leaked one has no automatic end.
An expired key is refused with 401 KEY_EXPIRED, and a cancelled one with 401 KEY_REVOKED. Neither can be brought back. Make a new key.
GET /api/v1/key tells you which key you are using and what it may do. Every key may call it, it spends no credits, and it does not count towards the test cap. It is the quickest way to check a new key.
curl https://business.pcific.ai/api/v1/key \
-H "Authorization: Bearer $PCIFIC_TEST_KEY"{
"id": "c2f0f6b0-6b43-4c0e-9d3a-0a1a8f5d2b11",
"name": "Local testing",
"kind": "test",
"prefix": "pcific_test_AbCd",
"can": [
"orbit",
"safeguard",
"ask-pcific",
"pixel-trace",
"read"
],
"expiresAt": "2026-12-18T09:00:00Z",
"dailyCap": {
"limit": 200,
"usedToday": 0
}
}can lists the permissions. expiresAt is null for a key with no end date. dailyCap is for test keys only (live keys show null): limit is always a number, bounded by PCIFIC’s server ceiling or your lower saved cap, and usedToday is how many AI requests your test keys have made today.
Test keys spend no credits. Each shop has its own daily cap, shared by all test keys used for that shop. PCIFIC’s ceiling is 200 AI requests per shop per UTC day by default. Owners and admins can lower their cap on the API keys page, but cannot raise it above the ceiling. Past it, test requests for that shop are refused with 429 TEST_DAILY_CAP_REACHED. Wait until midnight UTC for the count to reset, or use a live key. If you chose a lower cap, you can restore PCIFIC’s ceiling under API keys.
| Counter | What it counts |
|---|---|
| Daily AI cap | Each shop has its own allowance, shared by all test keys used for that shop: starting an Orbit listing or Safeguard review, sending their answers, retrying them, and each Ask PCIFIC question. PCIFIC-side failures are given back. Resets at midnight UTC. |
| Usage uses | Successful starts of listings, reviews, questions and photo groups, plus photo and device checks; answers, retries, reads and saved replies to repeated calls do not add uses. A successful start counts even if its background work fails later. |
| Usage requests | All recorded tool calls linked to your business this month, including failures and repeated calls, from test and live keys. Setup and reads, and refusals with no known tool, remain in Logs. Missing or unrecognised keys cannot be linked to your business and are excluded. |
Live keys spend credits from your business's one balance when a tool does its work, and each charge is recorded against the shop it was for. You can set a daily, weekly and monthly spending limit for each shop on the Usage page, or with PUT /api/v1/spend-limits?marketplaceId=<id>. When a shop's limit is reached, that shop's requests from live keys that spend credits are refused with 429 SPEND_LIMIT_REACHED until the limit is raised or the window starts again. Your other shops carry on. It stops requests, it does not only warn. Owners and admins are also emailed, naming the shop, as a limit is neared and when it is reached. Test keys are never affected.