Skip to Content
API Access

API Access

Veref exposes a machine-to-machine API for recruiters and partner systems. Auth uses bearer tokens issued per tenant. Each call links back to the issuing recruiter and is logged in the tenant audit trail.

Token format

vrf_<env>_<prefix>_<secret>
  • env — live or test
  • prefix — 12-char public identifier (safe to log)
  • secret — 40-char secret segment (treat like a password)

Tokens are hashed (SHA-256 + API_KEY_PEPPER) before storage. The plaintext is shown once at creation; lost keys must be re-issued.

Issuing a key

Recruiters issue keys from Settings → API keys in the recruiter app, through veref login, or via the Clerk-authenticated management endpoint:

curl -X POST https://api.veref.work/v1/tenants/$TENANT/api-keys \
  -H "content-type: application/json" \
  -H "authorization: Bearer $CLERK_SESSION_JWT" \
  -d '{
    "name": "Production webhook",
    "environment": "live",
    "scopes": ["references:read", "reports:read"]
  }'

Response includes apiKey (metadata) and plaintext (token, copy now).

Leave scopes empty to grant all scopes. expiresAt is optional; keys without an expiry stay valid until revoked.

Authenticating requests

Pass the token in either header:

Authorization: Bearer vrf_live_abc123def456_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
x-api-key: vrf_live_abc123def456_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

For the CLI, install the public package and use browser login:

npm install -g @verefwork/cli
veref login

The CLI opens the recruiter app, issues a tenant-scoped API key from the authenticated Clerk session, and stores the key in macOS Keychain. On platforms without secure credential storage, use an environment variable instead, or explicitly opt into a chmod 600 plaintext file with VEREF_ALLOW_PLAINTEXT_CLI_CREDENTIALS=1.

The production defaults are https://api.veref.work and https://app.veref.work. Use --api-url, --app-url, VEREF_API_URL, or VEREF_APP_URL only for local and staging environments.

For non-interactive jobs, set:

export VEREF_API_KEY=vrf_live_abc123def456_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Then run API-key backed commands with:

veref references start --json reference-request.json

Scopes

ScopeGrants
references:readRead reference requests, responses, and reports
references:writeCreate reference requests, send invitations
reports:readRead reference reports
reports:writeGenerate, share, or revoke reports
candidates:readRead candidate profiles linked to references
candidates:writeCreate or update candidate records
valuations:readRead reference valuation outputs
valuations:writeTrigger reference valuation runs

A key without explicit scopes inherits all scopes. Calls missing a required scope return 403.

Revocation

curl -X DELETE https://api.veref.work/v1/tenants/$TENANT/api-keys/$KEY_ID \
  -H "content-type: application/json" \
  -d '{ "revokedById": "recruiter_123", "note": "Rotated" }'

Revoked keys reject immediately. Revocation is permanent — re-issue a new key to restore access.

Auditing

Every authenticated call writes:

  • An ApiKeyUsage row (endpoint, method, status, duration, IP hash, trace id)
  • An AuditEvent row when the call mutates business state, with actorKind: api_key and actorId set to the issuing key

Recruiters see usage in Settings → API keys → Last used; full audit trail is queryable via the recruiter workspace API.

Environments

  • live — production tenant data
  • test — sandbox tenant data; same surface, isolated records

Pick the environment at key creation. A test key cannot read live data and vice versa.

Rate limits and IP allowlists

Not enforced in v1. Per-key quotas and IP allowlists are on the roadmap; usage telemetry is already captured to inform the limits.

Webhooks

Webhooks ship in a follow-up release. The API key surface only covers synchronous request/response calls today.

Agent workflow routes

External agents should use the API-key routes under /v1/api. The full route list is in Endpoint Reference; the CLI workflow is in Agent CLI.

POST /v1/api/agent is the headless Ask Veref route. It uses the tenant and recruiter identity from the API key, defaults to the configured OpenRouter Gemini 3 model chain, and only runs tools allowed by the key scopes.

OpenAPI

The API serves the external API-key contract as OpenAPI:

  • Swagger UI: https://api.veref.work/docs
  • JSON spec: https://api.veref.work/openapi.json

The generated spec is scoped to the public /v1/api integration surface. Recruiter UI routes, local development routes, and internal operations routes remain documented separately in Endpoint Reference.

IntegrationsEndpoint Reference