DocsUsing withHuman

API keys

Choose personal or organization API keys for scripts and integrations.

Updated Sep 24, 2026

API keys let scripts and integrations use withHuman without an open browser session. Each key belongs to one organization and allows only the actions covered by its permissions.

Key types

Use a personal API key for a script that acts as you. Use an organization API key for a shared integration that needs its own access. Organization API keys are a hosted edition feature; the open edition offers personal keys.

	Personal API key	Organization API key
Acts as	The member who created it.	The key itself.
Access	Follows the member's current permissions, optionally limited to selected actions.	Has its own permission policies and resource scopes.
When the creator leaves	Removing the member revokes their keys.	Keeps working independently of the creator.
Request decisions	Can decide with the member's approval permission, subject to the same review rules.	Cannot claim, approve or deny requests.
Typical use	A personal reporting script or review client.	A shared reporting or configuration integration.

Loading diagram…

Diagram source

mermaid

flowchart TD
    member["Your current permissions"] --> personal["Personal API key"]
    limit["Optional limit on actions"] --> personal
    policies["The key's own permission policies"] --> organization["Organization API key"]
    personal --> yours["Your script acts as you"]
    organization --> shared["Shared integration acts as the key"]

Personal API keys explains inherited access and membership changes. Organization API keys explains independent policies and scopes.

An agent that asks for approval uses an agent instance credential, rather than either kind of API key. Provisioner tokens let deployment platforms register those instances.

Either kind of key also lets a coding agent or assistant configure withHuman for you through the withHuman MCP server.

Secrets and expiry

The full secret appears only when a key is created. Save it in your script's or integration's secret storage; it cannot be retrieved later. The key list shows a public prefix for identification, not a usable credential.

An expiry date ends access automatically. A deployment may impose a maximum lifetime, including on keys requested without an expiry. Use the saved key's Expires value to plan its replacement.

Rotation means creating a replacement, updating the integration and revoking the old key. Revocation stops further API calls immediately and cannot be undone. Expired and revoked keys remain in the list for history.

API access

Both types use the Authorization: Bearer header. With the secret supplied through WITHHUMAN_API_KEY, this read-only call checks the key:

curl --fail-with-body --silent --show-error \
  https://app.withhuman.ai/api/v1/api_keys/verify \
  --header "Authorization: Bearer $WITHHUMAN_API_KEY"

For a self-hosted deployment, replace https://app.withhuman.ai with its origin. The response includes the key's details, current permissions and resource scopes. It confirms authentication and access at that moment; the operation your integration calls still needs to allow that key type and permission.

Key creation and revocation require a signed-in person. An API key cannot create more keys or revoke them.

See the API keys reference for operations and response fields, and Audit log for key activity.