Authentication

Every endpoint except GET /health and GET /docs requires an API key, sent as a bearer token:

curl "https://external-api.paraform.com/api/external/v1/identity" \
  -H "Authorization: Bearer pf_live_…"

Keys start with pf_ followed by the key’s environment (for example pf_live_). The full key is shown exactly once, when you create it, and can’t be retrieved again. Store it in a secrets manager and only use it from your servers. Never put it in browser or mobile code.

Key types

Agency keys
Personal keys

An agency key acts as your agency’s API integration, not as any one person.

Who can create one: agency owners, on the API Keys tab of the agency settings (/agency/api-keys).
Availability: Paraform enables API access per agency. If you don’t see the API Keys tab, ask your Paraform contact.
Scopes: chosen when you create the key (see Scopes). The talent_network:* scopes are offered only when your agency has Talent Network access.
Limits: up to 50 active keys per agency. A key can have an optional expiry date and can be revoked at any time.

A personal key acts as you, the recruiter who created it, with the same access you have in the app.

Who can create one: any recruiter whose account has personal API keys enabled, on the API keys tab of the account settings (/manage/api-keys).
Availability: the API keys tab only appears for accounts that have access. If you don’t see it, ask your Paraform contact.
Scopes: chosen when you create the key (see Scopes).
Limits: up to 5 active keys per recruiter. A key can have an optional expiry date and can be revoked at any time. Only you can see or revoke your personal keys.
A personal key stops working if your account can no longer recruit on Paraform.

Scopes

Each endpoint requires one or more scopes, listed on its reference page. A key can call an endpoint only if it holds every scope the endpoint requires.

Scope	Key type	Grants
`identity:read`	Agency, personal	`GET /identity`
`talent_network:read`	Agency	Read your agency’s Talent Network data, for example members, submission batches, and candidate preferences
`talent_network:write`	Agency	Change your agency’s Talent Network data, for example upload resumes, submit candidates, and update preferences or market status
`agency_roles:read`	Agency	Read roles on behalf of an approved agency member
`roles:read`	Personal	Read role data, for example role listings, role briefs, and your saved preferences
`candidates:read`	Personal	Read your candidate data, for example CRM candidates, recommendations, and call transcripts

Agency keys also carry talent_network:read automatically, whatever scopes you picked, so GET /identity lists it. Personal keys can’t hold agency scopes, so agency-only endpoints, such as the Talent Network endpoints, answer 403 for them.

Authentication errors

Status	`type`	When
`401`	`authentication_error`	The `Authorization` header is missing, or the key is invalid, expired, or revoked
`403`	`permission_error`	The key is valid but lacks a required scope, or the action isn’t permitted for this key (the message says why)

See Errors for the full error format.

Check your key

GET /identity returns who your key acts as (principal is agency or recruiter) and its effective scopes. Use it as a connectivity and configuration check before anything else.

Overview

Using the API

Key types

Scopes

Authentication errors

Check your key

​Key types

​Scopes

​Authentication errors

​Check your key

Key types

Scopes

Authentication errors

Check your key