Workspace API keys

A workspace API key works in one workspace only. Use one for CI/CD or automation that should reach a single workspace's clusters and apps, and nothing else in your organization.

How a workspace key differs from an org-wide keyCopy Anchor Link

Role ceilingCopy Anchor Link

When you create a workspace key, it gets a role ceiling: your role in that workspace at that moment. If you're an org admin, the ceiling is admin. The ceiling decides which scopes the key can have.

You choose the scopes when you create the key. A key can't have more than its ceiling allows.

The ceiling doesn't change after the key is created. If your role in the workspace changes, the key keeps the authority it was created with. If you're removed from the workspace or leave the organization, SkaleData revokes the workspace keys you created there. To stop a key yourself, revoke or delete it, or set an expiry when you create it.

Create a workspace keyCopy Anchor Link

1. In the SkaleData console, go to Organization > API Keys.
2. In Workspace API keys, pick the workspace, and then click Create key.
3. Enter a name, choose the scopes, and optionally choose when the key expires.
4. Click Create key, and then copy the key. It's shown only once.

You can also create one with the API, using a user session:

curl -X POST https://api.skaledata.com/workspaces/<workspace-id>/api-keys \
  -H "Authorization: Bearer <clerk-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-deploy", "scopes": ["apps:deploy", "clusters:read"], "expires_in_days": 90}'

The response includes scope_kind, workspace_id, and role_ceiling. Check that scope_kind is workspace and workspace_id is the workspace you asked for before you store the key.

Or use the skale CLI, signed in with skale login. Name the workspace by its ID, slug, or name:

skale api-keys create --workspace analytics --name ci-deploy \
  --scope apps:deploy --scope clusters:read --expires-in-days 90

The CLI prints the key only when the response confirms a workspace key in the workspace you named. A stored API key can't create or list keys.

What a workspace key can reachCopy Anchor Link

• Resources in its workspace, within its scopes. A cluster, app, or job in another workspace or another organization returns 404, as if it doesn't exist.
• Not organization administration. Organization settings, billing, clouds, members, and API key management return 403.
• App URLs through the proxy (for example, an Airflow or Superset URL) only with the admin ceiling and the full scope. Any other workspace key gets 403 there, because requests through the proxy run as the app's admin identity.
• Not the SkaleData MCP gateway. It returns 403 for workspace keys. Use an org-wide key instead; see Connect other MCP clients with an API key.

Open terminals, pod log streams, and proxied connections made with a workspace key end when the key expires. If the key is revoked, or its cluster moves to another workspace, they end within about a minute.

Manage workspace keysCopy Anchor Link

In Organization > API Keys > Workspace API keys:

• Workspace admins and org admins see and manage every key in the workspace.
• Everyone else sees and manages the keys they created there.

To revoke or delete a key, click Revoke or Delete on its row. A revoked key stays in the list; a deleted key is removed.

Find the keys you've createdCopy Anchor Link

Your workspace API keys on the API Keys tab lists the workspace keys you created, in every workspace, including keys that were revoked when you lost access to a workspace. You can revoke or delete them there, or with the CLI or the API:

skale api-keys list
curl https://api.skaledata.com/me/api-keys -H "Authorization: Bearer <clerk-jwt>"
curl -X POST https://api.skaledata.com/me/api-keys/<key-id>/revoke -H "Authorization: Bearer <clerk-jwt>"

This works only while you're a member of the organization.