PermuteDocs
Go to Permute

Identity and access

API keys

Create a key for an integration, choose its resource access, and control when it expires.

API keys authenticate integrations that call the REST API or server SDK. Give each integration its own key with access to the resources it needs. For interactive CLI and SDK work, you can sign in with your Permute account instead.

Create a key

In app.permute.ai, open Organization Settings → API Keys and choose Create API Key. Select the organization or workspace boundary, resource permissions, and expiration. Copy the key when it is created; it is shown once.

Keys need their own grants and do not inherit their creator’s access. An organization-wide key still needs resource permissions within the selected workspace. See Permissions and sharing.

Authenticate a request

Send the key in the bearer authorization header.

http
Authorization: Bearer $PERMUTE_API_KEY

Choose a workspace

Workspace-scoped keys infer their workspace. Organization-scoped keys must include the workspace ID on data operations. Workspace IDs begin with wksp_.

http
Authorization: Bearer $PERMUTE_API_KEY
X-Workspace-Id: $PERMUTE_WORKSPACE_ID
Content-Type: application/json

In the SDK, use client.withWorkspace(id) for workspace calls.

Set an expiration

New keys expire after one week by default. Choose 1 day, 1 week, 1 month (30 days), or a custom expiration date and time. Forever removes the fixed deadline and shows a warning.

New keys also expire after 30 days without use; change this interval or turn it off in Advanced settings. Each authenticated request restarts the inactivity clock (never-used keys count from creation), and whichever expiry comes first ends access. Existing keys keep their expiration settings.

Protect and revoke keys

Keep keys in your integration’s secret store. Never include them in browser code, source control, or shared examples. Hosted apps use the browser SDK and the viewer’s sign-in session.

Revoke a key in Organization Settings → API Keys when the integration no longer needs it or the key is exposed. Review keys separately when someone leaves: ending their login does not revoke machine keys.