Skip to content

Authentication

Every request carries an API key. A key belongs to one business and acts for it, not for a person, so it keeps working when you sign out and doesn't need a password.

Create a key

  1. Sign in as an admin or the owner of the business.
  2. Open Settings → API keys and choose Create key.
  3. Give it a name that says where it is used ("Website forms", "Zoho CRM sync"), pick a role, and choose when it expires (never, or in 30 days, 90 days or a year).
  4. Copy the key straight away. It starts with aiw_ and is shown only once; we store only a fingerprint of it.
Keep keys on your server
A key can read your leads and start calls that use your credits. Keep it in a server-side secret or environment variable, never in website JavaScript, a mobile app or a public repository. If one leaks, revoke it at once.

Send it with each request

Put the key in the Authorization header as a bearer token:

Request
curl "https://progz.in/api/v1/leads?limit=5" \
  -H "Authorization: Bearer aiw_your_key_here"

The key already knows its business, so you don't send a business id. (If you do send X-Workspace-Id, it must be the key's own business, or the request gets 404.)

Roles: what a key may do

Choose the smallest role that does the job. A key can never be an owner.

RoleCanUse it for
viewerRead leads, candidates, contacts, bookings, conversations and campaigns.Reporting, dashboards, syncing results into a CRM.
memberEverything a viewer can, plus create and update leads, candidates and contacts, ask for calls, run campaigns and cancel bookings.Website and CRM integrations. The usual choice.
adminEverything a member can, plus change AI employees, knowledge, workflows and integrations.Only if your integration manages setup itself.

A key never has more access than the person who created it. It acts with the lower of its own role and that person's current role, and it stops working if they leave the business.

What keys cannot do

Some things always need a person signed in to the app: their own account and password, the team and invites, creating businesses, and managing API keys themselves. A key sent there gets 401 api_key_not_allowed (or 403 api_key_forbidden for API key management).

Expire, rotate and revoke

  • Expiry: a key that expires stops working at that moment. Choose "Never" for a key that lasts until revoked.
  • Rotate without downtime: create a new key, deploy it, check that requests succeed, then revoke the old one.
  • Revoke in Settings → API keys. It stops working on the next request. The list also shows when each key was last used, which helps you find keys nobody needs any more.

A revoked, expired or unknown key gets 401 invalid_api_key. See Errors for the full list.