API Keys¶
An API key lets a program call AgentZ for you. You create keys under your account. Each key belongs to you and targets one workspace.
You need a workspace in the Ready state with at least one agent. See Create a workspace and Create an agent. Without them, the page shows No eligible Workspaces.
Two Key Types Cover Two Jobs¶
| Type | Key prefix | What it authorizes |
|---|---|---|
| Agent | opk_ | Access to the agents you select |
| Webhook | whk_ | Calls to the webhooks of the workflows you select |
A caller sends a Webhook key in the X-API-Key header to start a workflow run. See Webhooks.
Create a Key¶
- Open your account menu and select API keys. The API keys page opens.
- Select New API key. A list titled Choose a workspace opens.
- Choose the workspace. The Create API key dialog opens.
- Under Type, choose Agent or Webhook.
- Enter a Name. The limit is 32 characters.
- Under Expiry, choose No expiry, 7 days, 30 days, 90 days or 365 days.
- Under Accessible Agents or Accessible Workflows, select the targets.
- Select Create API key. The dialog title changes to Copy your API key.
- Select Copy, store the key, then select Close. The key appears in the table with the status Active.
Warning
The dialog says "This secret is shown once. Store it now." AgentZ cannot show the key again. If you lose it, revoke the key and create a new one.
The table on the API keys page lists each key with its Name, Workspace, Targets, Status and Expires values.
Pick the Shortest Expiry That Works¶
A key with No expiry works until you revoke it. A key with an expiry shows Expired in the Status column after that date.
Use 7 days for a test. Use a longer expiry for a job that runs for months, and rotate the key before it ends.
Revoke a Key¶
- Open API keys from your account menu.
- Open the menu on the key row and select Revoke.
- Select Revoke in the Revoke API key? dialog. The toast says API key revoked.
The row then shows Revoked. Calls with that key stop working.
Next Step¶
Continue with Audit and observability.