API Authentication
Generate and manage API keys for authenticating with the WorkClaw REST API. Learn about key scopes, rotation, and security best practices.
How do I authenticate API requests?
All WorkClaw API requests require a valid API key in the Authorization header using the Bearer scheme:
Authorization: Bearer wc_live_xxxxxxxxxxxxxxxxxxxx
Requests without a valid key receive a 401 Unauthorized response.
How do I generate an API key?
- Navigate to Settings > API Keys in the WorkClaw dashboard.
- Click Create Key.
- Enter a descriptive name for the key (e.g., "CI/CD Pipeline" or "Custom Dashboard").
- Select the scopes the key should have (see below).
- Click Generate.
- Copy the key immediately -- it is displayed only once and cannot be retrieved later.
Store the key securely, ideally in a secrets manager or your Vault.
What scopes are available?
API keys can be scoped to limit their access:
| Scope | Access |
|---|---|
claws:read | List and view Claw configurations |
claws:write | Create, update, and delete Claws |
deployments:read | View deployment status and history |
deployments:write | Trigger deployments and rollbacks |
skills:read | List installed skills |
skills:write | Install, update, and remove skills |
team:read | View team members and roles |
team:write | Invite members and update roles |
chat:write | Send messages to a Claw |
chat:read | Retrieve conversation history |
Follow the principle of least privilege -- grant only the scopes your integration needs.
How do I rotate a key?
Navigate to Settings > API Keys, find the key, and click Rotate. WorkClaw generates a new key and keeps the old key active for a grace period (default 24 hours) so you can update your integrations without downtime. After the grace period, the old key is revoked automatically.
What are the security best practices?
- Never embed keys in client-side code -- API keys should only be used in server-side applications or CI/CD environments.
- Use scoped keys -- avoid full-access keys when a narrower scope is sufficient.
- Rotate regularly -- set a rotation schedule (e.g., every 90 days).
- Monitor usage -- check the API key activity log under Settings > API Keys for unexpected access patterns.
- Revoke unused keys -- delete keys you no longer need to reduce your attack surface.
If you suspect a key has been compromised, revoke it immediately from the dashboard and generate a replacement.