Accounts and team

An account owns API keys, verifications and billing. People join an account as members with a role. The dashboard signs people in with a magic link; API keys never expire and belong to the account, not to a person.

Sign up

curl -X POST https://api.primarycheck.com/v1/signup \
  -H "Authorization: Bearer pc_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "amy@mercystaffing.com",
    "name": "Amy Rivera",
    "company": "Mercy Staffing"
  }'

Creates the account, its first owner and a default pc_test_ key, and mails a sign-in link. 409 email_in_use when the address already has an account. Outside production the response also carries loginUrl so local development needs no mailbox.

Magic-link sessions

Step	Call	Result
1	`POST /v1/sessions { email }`	Always `202 { sent: true }`; a link is mailed only when the address is known. Never reveals whether an email exists.
2	The person opens the link (valid 15 minutes, single use)	The dashboard receives `?token=`
3	`POST /v1/sessions/exchange { token }`	`{ sessionToken: "pcs_…", user, account, role, expiresAt }`; the session lasts 30 days.
4	`DELETE /v1/sessions/current`	Sign out (204).

A session token is sent exactly like an API key (Authorization: Bearer pcs_…). Orders placed under a session are recorded as dashboard channel in usage. Some calls require a session rather than a key: creating or revoking API keys, changing the account, managing members.

Roles

Role	Can
`owner`	Everything, including granting the owner role and removing owners. An account always keeps at least one owner.
`admin`	Create live and test keys, manage members and invites (not owners), update the account, order and read everything.
`member`	Order verifications, create test keys, read everything.
`viewer`	Read only. Any non-GET request returns 403 read_only_role.
`ops`	PrimaryCheck staff only, on staff accounts.

API keys

curl -X POST https://api.primarycheck.com/v1/api_keys \
  -H "Authorization: Bearer pc_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ATS production",
    "mode": "live"
  }'

{ "id": "key_…", "name": "ATS production", "mode": "live", "prefix": "pc_live_3kd9",
  "createdAt": "2026-11-03T14:05:09Z", "lastUsedAt": null, "revokedAt": null,
  "key": "pc_live_3kd9…"            ← shown once }

GET /v1/api_keys lists keys with prefix, creation, last use and revocation; never the secret.
DELETE /v1/api_keys/{id} revokes immediately (owner or admin). Requests with a revoked key return 401 invalid_api_key.
mode is live or test; test keys work only against the sandbox host. Live keys are issued once the account's FCRA vetting is approved.
Each key has its own per-second limit and the account a per-minute limit; see Rate limits.

Team members and invites

Call	Who	Notes
`GET /v1/account/members`	any member	id, userId, email, name, role, createdAt
`POST /v1/account/members/invites { email, role }`	owner, admin	Mails an invite valid 7 days. 409 already_member if the address is on the account.
`POST /v1/invites/{token}/accept { name? }`	the invitee (no auth)	Joins the account and returns a session.
`PATCH /v1/account/members/{id} { role }`	owner, admin	Only an owner touches owners. 409 last_owner protects the final owner.
`DELETE /v1/account/members/{id}`	owner, admin	204.
`PATCH /v1/account { name }`	owner, admin	Rename the account.

Audit

Every sign-in, key creation, invite, role change, order and report download is written to the account audit log with the actor (user:… or key:…), IP and timestamp, and can be exported with GET /v1/account/audit.