> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys & System Keys

> Workspace keys, tenant-scoped system keys, and the permission boundary between them

Programmatic access to the platform uses **API keys**. There are two kinds, separated by a security boundary that is enforced in code: ordinary **workspace keys** and **system keys**.

## Workspace keys

A workspace key is **scoped to a single workspace** and inherits a set of `resource:*` permissions (read, edit, delete, run, advanced, plus opt-in scopes like `sandboxes:run`). It's the key you use for the [SDK](/sdk/concepts/authentication), [REST API](/api-reference/introduction), and [MCP server](/sdk/mcp/overview). Create one in **Settings → Organization → Workspaces → (pick a workspace) → API Keys**.

A workspace key can read and drive resources **within its workspace**. It can never perform tenant-wide administration — and, by design, it can't even hold the permissions that would allow it.

## System keys

Some operations are **tenant-wide**, not workspace-scoped: creating or inviting users, creating/deleting workspaces, managing providers, billing, and org-level settings. These require the tenant-wide permissions:

```
users:read   users:invite   users:delete
workspace:read   workspace:create   workspace:delete
providers:manage   billing:manage   org:admin   org:analytics
```

Those permissions may live **only** on a **system key** — an API key homed in the tenant's hidden `admin` **system workspace**. This is a hard invariant, enforced in two places:

* **At mint time** — a request to put any tenant permission on an ordinary workspace key is rejected.
* **At resolution time** — a tenant-scoped endpoint only accepts a key that actually resides in the admin system workspace, even if a permission somehow ended up on a workspace key.

<Info>
  The net effect: a leaked workspace key can never escalate to tenant
  administration. The blast radius of a workspace key is exactly its workspace.
</Info>

### Minting system keys

Only a **tenant admin** can create system keys. They're managed through the admin surface:

* **SDK** — `client.admin.create_system_key(name, permissions=[...])`. See [Admin](/sdk/resources/admin).
* **REST** — `POST /v1/admin/system-keys`. See the [System keys API](/api-reference/v1--system-keys/list-system-keys).

Grant a system key only the tenant permissions it needs (e.g. a provisioning bot that creates workspaces needs `workspace:create`, not `billing:manage`).

## Operating guidance

<CardGroup cols={2}>
  <Card title="Scope tightly" icon="crosshairs">
    Give each key the minimum permissions for its job. Prefer a workspace key unless the task is genuinely tenant-wide.
  </Card>

  <Card title="Rotate & revoke" icon="rotate">
    Rotate keys periodically and delete unused ones. A key's value is shown once at creation — store it in a secret manager.
  </Card>

  <Card title="Never ship in clients" icon="mobile-screen">
    Keys are secrets. Keep them server-side or in trusted environments; never embed them in browser or mobile apps.
  </Card>

  <Card title="Audit" icon="clipboard-list">
    Key-driven actions are attributed to the key. See [Auditability](/deployment/security/auditability).
  </Card>
</CardGroup>

<Note>
  See also [Authentication](/deployment/security/authentication) and
  [Authorization](/deployment/security/authorization) for how keys and permissions
  are verified across the platform.
</Note>