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

# Creating and Managing API Keys

> Create user, workspace, and organisation API keys to securely connect external tools to Share Of Model.

API keys let you connect external tools or integrations securely to your account. Three key types exist, each with distinct permissions and creation requirements.

All keys are prefixed with `sk-som-`. A key is not itself a credential you send on API calls — you exchange it for a short-lived JWT first, as described in [Authentication](/api-reference/authentication).

## Key types

<CardGroup cols={3}>
  <Card title="User API key" icon="user">
    Inherits the permissions of the user who created it. Use when an integration must act as a specific user. Limited to **5 per user**.
  </Card>

  <Card title="Workspace API key" icon="building">
    Created by users with the **Workspace Editor** role. Grants API access to a single workspace.
  </Card>

  <Card title="Organization API key" icon="sitemap">
    Created by **Organization Owners**. Grants API access across the entire organisation.
  </Card>
</CardGroup>

<Note>
  Workspace and organisation keys carry a **role**, which you pick when creating the key. The role caps what the key can do, using the same roles described in [User Roles & Workspaces](/platform/getting-started/user-roles-and-workspaces-management) — so a read-only integration should be issued a Viewer key rather than an Editor one.
</Note>

## How to create API keys

<Tabs>
  <Tab title="User API key">
    Use this when an integration should act as you.

    <Steps>
      <Step title="Open your profile">
        Click your **profile icon** in the bottom-left corner, then click your **name**.
      </Step>

      <Step title="Go to API Keys">
        Open the **API Keys** section.
      </Step>

      <Step title="Create the key">
        Click **Create API Key** and enter a name.
      </Step>

      <Step title="Copy the key now">
        <Warning>
          Copy the key immediately — it will not be visible again later.
        </Warning>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Workspace API key">
    Use this for workspace-level integrations.

    <Note>
      You must have the **Workspace Editor** role (or higher) to create a workspace API key.
    </Note>

    <Steps>
      <Step title="Open Settings">
        Click your **profile icon** in the bottom-left, then click **Settings**.
      </Step>

      <Step title="Pick the workspace">
        Select the workspace you want to manage.
      </Step>

      <Step title="Open the API section">
        Open **API** in the left panel. (If you see **Workspace Settings** instead of Settings, click that — it leads to the same place.)
      </Step>

      <Step title="Create the key">
        Click **Create API Key** and enter a name.
      </Step>

      <Step title="Copy the key now">
        <Warning>
          Copy the key immediately — it will not be visible again later.
        </Warning>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Organization API key">
    Use this for organisation-wide integrations.

    <Note>
      You must be an **Organization Owner** to create an organisation-level API key.
    </Note>

    <Steps>
      <Step title="Open Settings">
        Click your **profile icon** in the bottom-left, then click **Settings**.
      </Step>

      <Step title="Open the API section">
        Open **API** in the left panel.
      </Step>

      <Step title="Create the key">
        Click **Create API Key** and enter a name.
      </Step>

      <Step title="Copy the key now">
        <Warning>
          Copy the key immediately — it will not be visible again later.
        </Warning>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Rotating a key

You do not have to delete a key and rebuild the integration to change its secret. Rotating a key issues a new secret and invalidates the previous one, keeping the key's name, scope and role intact — so you can roll credentials on a schedule, or immediately if one leaks.

Rotation is available from the same **API** panel where you created the key, and through the **API Key** endpoints in the [API Reference](/api-reference/introduction).

<Warning>
  Rotation takes effect immediately. Any integration still holding the old secret will start receiving `401` responses, so update your secret store first.
</Warning>

## Best practices

<Tip>
  * Treat API keys like passwords — never share them publicly.
  * Prefer the narrowest scope that works: a workspace key over an organisation key, and a Viewer role over an Editor one.
  * Rotate keys regularly and delete unused ones.
  * Store them in a secret manager or environment variable, not in source code.
</Tip>

## What's next

<CardGroup cols={2}>
  <Card title="API Documentation Guide" icon="code" href="/platform/getting-started/api-documentation-user-guide">
    Use your key to make your first call.
  </Card>

  <Card title="MCP Server Setup" icon="plug" href="/platform/getting-started/get-started-with-share-of-model-mcp">
    Connect AI assistants to Share Of Model.
  </Card>
</CardGroup>