Authentication & permissions

Create, rotate, and revoke API credentials; choose scopes and understand account access requirements.

Every CVViZ API request requires a customer API credential. Credentials belong to one CVViZ account and cannot be used to access another account's data.

Create a credential

An authorized administrator or user with API credential management permission can manage credentials from Settings → Integrations & Tools → Developers.

When creating a credential:

Enter a Credential name that identifies the integration.
Review Permissions. View jobs and View candidates are selected initially. Remove unneeded permissions, select required scopes and check the selected count.
Review Expiry. Choose Account default (recommended), 30 days, 90 days, or Custom. Account default uses your account's recommended credential lifetime. Review the offered date and validation before creating the credential; the supported maximum lifetime is 365 days.
Choose Create credential, then copy the generated secret immediately. It is displayed only once.
Store it in a server-side secret manager.

Create separate credentials for separate integrations. If Create credential is disabled, review the active credential limit and unused credentials before changing your setup.

Rotate or revoke a credential

In API credentials, find the intended active credential and choose Rotate.
Keep its permissions, or select Change permissions on the replacement credential and choose the required scopes.
Review Overlap period in seconds. The default is 600 seconds (10 minutes); the supported range is 0 to 86,400 seconds. The old credential stops working at the end of this period or its existing expiry, whichever comes first. A zero overlap stops its use immediately.
Review Replacement expiry (optional), then choose Rotate credential.
Save the new secret when it is shown and update the integration before the old credential stops working. Confirm a permitted read request succeeds with the replacement.

Rotation issues a new credential. Idempotency receipts belong to the original credential, so reconcile an uncertain write before retrying it with the replacement. See Safe retries & idempotency.

Use Revoke when a credential should no longer authorize requests. Check which integrations depend on it and review the confirmation. Revocation does not undo operations already completed. If a credential may have been exposed, replace and revoke it promptly.

Send the credential

Send the secret in the HTTPS Authorization header using the Bearer scheme:

Authorization: Bearer YOUR_API_SECRET

Do not send credentials in URLs, query parameters, browser code, mobile applications, public repositories, logs, or support messages.

Scopes used by the published API

Scope	Grants access to
`jobs.read`	Read jobs and job pre-screening questions.
`jobs.write`	Create jobs, update approved core job fields and job tags, and manage the supported publication flags. Creation follows the account approval workflow.
`jobs.status.write`	Change supported lifecycle codes on existing jobs (see job options). Does not grant approval bypass, publication or deletion.
`candidates.read`	Read candidates, stages, tags, events, screening answers, benchmark resumes, and interview feedback.
`resumes.download`	Download original candidate resumes and explicitly request temporary direct file URLs, subject to content-access policy.
`candidates.profile.write`	Update approved candidate profile fields.
`candidates.write`	Add candidate tags and update a candidate application's stage.
`applications.read`	Read candidate and job associations.
`applications.write`	Add an existing candidate to an existing job.
`organization.read`	Read users, departments, hiring managers, grades, client companies, industries, job functions, employer types and job options.
`notes.read`	Read non-private candidate and job notes. Tasks use their separate task scopes.
`notes.write`	Add non-private plain candidate and job notes.
`documents.read`	Read candidate-document metadata. This scope does not return file URLs or download credentials.
`tasks.read`	Read non-private candidate, job, and unassociated tasks.
`tasks.write`	Create non-private tasks and update tasks created by the same API credential.
`offers.read`	Read candidate job-offer metadata. This scope does not return signed file URLs or internal delivery details.

Grant every scope listed by the endpoint reference.

Adding scopes to CVViZ does not change existing credentials. Rotate a credential and explicitly select the additional scopes when an integration needs them.

jobs.write creates a job through the account's standard workflow: active when approval is disabled, or pending approval when it is enabled. jobs.status.write is separate because changing an existing job's lifecycle is a distinct operation. Publication is controlled by the supported publication fields under jobs.write and never bypasses approval or capacity checks.

candidates.read returns resume filenames and stable authenticated download links, but not file bytes or direct signed URLs. Downloading requires resumes.download. Requesting include=resume_download_url on candidate detail requires both scopes. General document uploads/downloads, resume imports and candidate creation remain unpublished.

Access requirements

Your plan or an active API add-on must include API access.

Authorization failures

401 Unauthorized: the credential is missing, malformed, expired, revoked, or invalid.
403 Forbidden: the credential is valid but lacks the required scope, or the account does not have active API access through its plan or API add-on.

Was this helpful?

Still need help? Ask the team