Authentication and scopes
Create a workspace key, grant the required access, and rotate it safely.
Every API request uses an API key associated with one workspace and its creating Admin. A key does not grant access to another workspace, even if its owner belongs to both.
Create your first key
- Sign in as a verified workspace Admin and confirm the workspace name.
- Open Settings → Developer → API keys. API access must be enabled for the workspace.
- Enter a name identifying the consuming system, choose the scopes it needs, and set an expiry.
- Copy the one-time key into your backend's secret store. Do not put it in source control or a public frontend.
- Make a read request for a scope on the key and confirm that the returned data belongs to the intended workspace.
Keys expire after 1–365 days; the default is 90. A workspace can have ten active keys. If you lose a key's secret, create a replacement rather than trying to retrieve it.
Choose scopes
| Scope | Allows | Typical use |
|---|---|---|
reports:read | Report lists, summaries, status, and detailed results | Synchronize evaluations into your ATS |
analyses:write | Upload preparation, quotes, submission, cancellation, and analysis/upload batches | Submit candidate resumes |
job-descriptions:read | Saved job discovery and content revisions | Attach applications to reviewed roles |
interviews:read | Interview lists, state, and evaluations | Follow candidate progress |
interviews:write | Quotes, invitations, resend, reinterview, and invitation batches | Invite candidates |
events:read | Retained event feed | Recover missed notifications |
Batch-status reads use the scope required to create that batch. An analyses:write key alone does not grant report reads. Webhook subscriptions and signing secrets are separate from API scopes.
Authenticate a request
Set PROBB_URL to your application origin and supply PROBB_API_KEY from your secret store:
curl --fail-with-body "$PROBB_URL/api/v1/reports?limit=1" \
-H "Authorization: Bearer $PROBB_API_KEY"This example requires reports:read. Authentication errors return 401; unavailable access or a missing scope returns 403. Check the key's workspace, expiry, and creating Admin's current access before generating more keys.
Rotate or revoke
Create a replacement with the required scopes, update the consuming backend, verify a request, then revoke the old key. Existing idempotency receipts survive key rotation, so retry an uncertain submission using its original request key and body.
Revocation, expiry, removal of the owner, or loss of the owner's verified Admin access stops API use. Accepted work can continue; stopping API access does not undo a submission already accepted. Remove credentials from the consuming system after revoking them.
Sandbox credentials
Sandbox keys start with probb_test_ and work only with the isolated sandbox. Production and sandbox keys are not interchangeable. The sandbox guide explains sample data, controlled scenarios, and reset behavior.