Skip to main content
Authenticate API requests with an API key or an OAuth access token. Both act with the authenticated user’s current permissions in one workspace.

Create an API key

Workspace members can create their own keys. Managing other members’ keys requires separate workspace permission.
1

Open API key settings

In the Windmill Dashboard, open Settings → API keys. The browser route is /s/{company}/config/api-keys.
2

Choose access and expiration

Select Create API key and enter a descriptive name, such as Employee reporting. Choose Read for searches and other read operations, or Read/write when your integration needs to change data. Choose an expiration, then select Create. The dialog initially selects Read/write and 90 days; select Read explicitly for the getting-started example.
3

Store the key

Copy the plaintext key into a secret manager. Windmill shows the full key only once. Keys start with wm_api_. If you lose the value, create a replacement and revoke the old key.

Send the bearer header

Use this header on every API-key request:
In a shell, load the key from secure storage into WINDMILL_API_KEY, then use:
Keep credentials on your server. Don’t embed keys in browser code, commit them to source control, or include them in shell history, support messages, screenshots, or request logs.

Understand permissions

A key inherits its creator’s current workspace permissions and is further limited by its selected access mode. A read/write key doesn’t grant employee-management permissions that its creator lacks. Resource visibility and access rules still apply. Read keys can call read operations such as Search employee profiles, even though that operation uses POST. They can’t call mutations such as Update an employee profile. A key belongs to the workspace where you created it. Changing the company ID in the URL doesn’t authorize access to another workspace, even if you belong to both.

Resolve authentication failures

  • 401: check the Bearer header, the full key value, and whether the key is expired or revoked. Replace an invalid key.
  • 403: check that the key belongs to the requested workspace, its access mode permits the operation, and its creator still has the required workspace and resource permissions.
See Errors for request IDs and other status codes.

Rotate or revoke a key

To rotate, create a new key, update your integration’s secret, and confirm a read request succeeds. Then revoke the old key from Settings → API keys using its Revoke action. Revocation prevents further use of that key. Revoke exposed or unused keys promptly. You can manage your own keys. Members with permission to manage all workspace keys can also manage other members’ keys. For applications that need user consent and refreshable credentials, follow OAuth.