API keys

Create and manage credentials for your company’s Workerbee SDK integrations.

Create a key

Every SDK request needs an API key. Keys belong to your company, and a company admin creates, rotates and revokes them in the Work Intelligence Console (WIC) under:

Settings › Workspaces & SDK › SDK API keys

Enter a descriptive key name, such as hris-sync.
Select the scopes your integration needs. The form initially selects all four; deselect unnecessary permissions. At least one scope is required.
Choose the allowed workspaces. For the SDK examples, select Default. Selecting no workspaces grants access to all company workspaces.
Optionally choose an Expires date. WIC uses the end of that day in your browser’s local timezone. An empty date means no expiry.
Select Create key, then Copy the full secret into your secret manager. The key is shown only once; select Done after storing it.

The secret is shown once

The key list shows only the prefix, scopes, workspace access, last use, and expiry. You cannot recover a full key from that list. If you lose the secret, rotate the key or create a replacement.

Choose scopes

Scope	Allows
`files:write`	Upload and complete files, retry failed processing, and delete sources.
`files:read`	List files, poll status, inspect ZIP children, and download source bytes.
`graph:read`	Ask graph questions with chat.
`assistants:manage`	Create, update, and delete non-default workspaces through the workspace API. Not needed for the top-level SDK examples.

The upload-and-query examples need the first three scopes. Listing existing files only needs files:read. Creating a workspace through the API does not create or manage API keys.

Workspace access

The SDKs automatically use your company’s Default workspace. A key restricted to other workspaces will fail those methods with 404 WORKSPACE_NOT_FOUND. Select Default when creating the key, or create a replacement with the intended access.

Workspaces aren’t privacy boundaries

Workspace selection does not guarantee department-level isolation of graph answers. Graph reads can be company-wide; an employee subject is a query filter, not an authorization boundary.

Store and use the key

bash

export WORKERBEE_API_KEY="YOUR_API_KEY"

powershell

$env:WORKERBEE_API_KEY = "YOUR_API_KEY"

Keep keys in server-side applications or local scripts, outside source control and browser bundles. Never paste them into logs or support tickets.

All three SDKs read WORKERBEE_API_KEY. They send authentication for you. For direct SDK API requests, use Authorization: Bearer YOUR_API_KEY. This guide covers SDK keys; other Workerbee integrations may have a separate authentication setup.

Rotate without interrupting an integration

Choose when the old key should stop working using the selector above the key actions: immediately, after 1 hour (default), after 24 hours, or after 7 days.
Select Rotate beside the active key and confirm. Copy the replacement secret when it appears.
Update the secret in every application using this key. Restart or redeploy applications if they load credentials only at startup.
Verify a normal SDK request with the replacement before the grace period ends. The old key stops at the selected deadline, or its original expiry if earlier.

Rotation keeps the original expiry

Rotation preserves the name, scopes, workspace restrictions, and original expiry. It does not extend the key’s lifetime or change its permissions. Create a new key when you need a new expiry or different access. Expired or revoked keys cannot be rotated.

Revoke a key

Select Revoke and confirm. The next request using that key is rejected immediately. Revocation does not delete uploaded data, and should not be treated as cancellation of already queued processing.

For a compromised credential, revoke it immediately and replace it. If both an old key and a rotated replacement must be disabled, revoke each active key.

Troubleshoot access

Message or symptom	What to check
`401 API_KEY_REQUIRED`	Set the full key in the process environment before starting your application.
`401 API_KEY_INVALID`	Check that the key hasn’t expired or been revoked, and whether the old key’s rotation grace period has ended.
`403 SCOPE_MISSING`	Create a replacement with the required operation scopes. Rotation keeps existing scopes.
`403 COMPANY_ADMIN_REQUIRED`	Ask a company admin to manage keys in WIC.
`404 WORKSPACE_NOT_FOUND`	The key must include the Default workspace. The same error can also mean a missing resource.
No Workspaces & SDK screen in WIC	Ask Workerbee support to enable SDK access for your company.
`429 RATE_LIMITED`	Reduce request frequency and respect Retry-After. Include the request ID when reporting persistent failures.

“Last used” is a periodically updated indicator, not a per-request audit log.

Last updated October 2, 2026

Was this page helpful?