Skip to Content
Getting StartedAuthentication

API Key Format

Every Celper AI API key follows the format celp_{32 hex chars} — 37 characters total. Pass your key via the X-API-Key header on every authenticated request:

curl https://api.celper.ai/v1/job-positions \
  -H "X-API-Key: celp_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Do not pass the key as a query parameter or in the request body. The X-API-Key header is the only supported method.

Never expose API keys in client-side code, browser bundles, or public repositories. Use environment variables on the server side.

Generating API Keys

  1. Log in to platform.celper.ai .
  2. Go to API Management.
  3. Click Generate API Key.
  4. Enter a descriptive name for the key (e.g., “Production Backend”, “Staging CI”).
  5. Select the scopes the key should have access to (see below).
  6. Optionally, configure an IP allowlist to restrict where requests can originate from.
  7. Click Create and copy your key immediately — it is only displayed once.

Scopes

API keys are scoped to specific permissions. A request that requires a scope your key doesn’t have will return a 403 SCOPE_INSUFFICIENT error.

Available Scopes
ParameterTypeRequiredDescription
read:jobsscopeOptionalList and retrieve job positions.
read:candidatesscopeOptionalList and retrieve candidate data.
write:candidatesscopeOptionalCreate, update, and delete candidates.
action:invitescopeOptionalSend interview invitations to candidates.
action:decidescopeOptionalSelect or reject candidates.
manage:webhooksscopeOptionalCreate and manage webhook subscriptions.

IP Allowlists

IP allowlists add an optional security layer to your API keys. When an allowlist is configured on a key, only requests originating from listed IP addresses are accepted. Requests from any other IP receive a 403 IP_NOT_ALLOWED error.

Allowlists support individual IP addresses — e.g., 203.0.113.50. Each entry is matched exactly against the request’s originating IP.

If no allowlist is configured, the key accepts requests from any IP address.

Key Rotation

You can rotate API keys at any time from the API Management dashboard. When you rotate a key:

  • A new key is generated with the same name, scopes, and IP allowlist.
  • A grace period (default 60 minutes, configurable from 0 to 1440 minutes) allows the old key to continue working temporarily.
  • After the grace period expires, the old key is permanently invalidated.

Always rotate a key if you suspect it has been compromised. Set the grace period to 0 for immediate invalidation in security-critical situations.

During the grace period, both the old and new keys are valid. Update all services to use the new key before the grace period expires.

Security Best Practices

  • Store keys in environment variables, never hard-coded in source code.
  • Never expose keys in client-side code — browsers, mobile apps, or any publicly accessible bundle.
  • Use the minimum required scopes — grant only the permissions each integration actually needs.
  • Configure IP allowlists for production — restrict keys to your server or CI/CD IP ranges.
  • Rotate keys regularly and immediately after personnel changes or suspected leaks.
  • Monitor API logs in the dashboard for unusual activity, unexpected IP addresses, or elevated error rates.

Error Responses

If authentication fails, the API returns one of the following errors:

Missing or invalid API key (401):

401

IP not allowed (403):

403

Insufficient scope (403):

403
OverviewJob Positions