Authentication

Every request is authenticated with a developer API key. Keys start with aw_ak_ and are created by a workspace admin in Workspace → API keys.

Send the key

curl https://api.agent-works.ai/tasks \
  -H "Authorization: Bearer aw_ak_…"

The /v1 endpoints also accept X-API-Key: aw_ak_….

What a key is

• A key belongs to one workspace and acts as the person who created it. Role limits apply: a key cannot do what that person cannot do.
• A key carries scopes. An endpoint outside those scopes answers 403. See Scopes.
• The key itself is shown once, at creation. AgentWorks stores only a hash.
• When the person who created the key is deactivated, the key stops working.
• A workspace can have up to 10 active keys.

Expiry

Choose how long a key is valid when you create it: 30, 90, 180, 365 or 730 days, or no expiry. The default is 90 days and the maximum is two years. An expired key answers 401.

Workspace admins get a notification 7 days and 1 day before a key expires. The key list also flags keys that are expired, about to expire, or unused for 90 days.

Rotate a key

Rotating gives you a new secret with the same name, scopes and expiry, and switches the old one off. To rotate without downtime, create a second key, deploy it to your integration, then revoke the old one.

Change scopes later

Use Edit scopes on a key to add or remove permissions. The change applies to the key's next request; the secret stays the same.

Revoke a key

Revoke switches a key off immediately. Do this as soon as a key may have been exposed — for example pasted into a chat, a ticket or a log.

What a key can never do

• Approve or reject a request that is waiting for a person.
• Change approval settings, per-action confirmations or the personal-data policy.
• Act in another workspace. A key from an agency workspace works in the agency workspace only; see Agencies.