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

# Service Accounts: Non-Human API & MCP Identities

> Create service accounts so API keys and MCP clients authenticate as a shared, non-human identity instead of a person. Access survives team changes and isn't tied to anyone's login.

## Overview

An API key tied to a person is fragile. When that person is deactivated or leaves, their keys stop working and every automation built on them breaks. A key bound to a service account keeps working through team changes, because the access belongs to the organization rather than to whoever happened to create it. You issue keys against the service account, and automations, scripts, and MCP clients (Claude, Cursor, Windsurf, and other agents) use them.

<Note>
  **Only organization administrators** can create, view, or deactivate service accounts and issue keys against them.
</Note>

## Use cases

<CardGroup cols={2}>
  <Card title="Connect MCP clients without personal login" icon="plug" href="/how-to/mcp-server">
    Point Claude, Cursor, Windsurf, or any MCP client at Wolfia with a service-account key. Your whole team shares one connection instead of each person doing a personal OAuth login, and the connection does not break when someone offboards.
  </Card>

  <Card title="CI/CD and scheduled automations" icon="robot" href="/how-to/api-overview">
    Run nightly knowledge syncs, scheduled questionnaire imports, or CI jobs that call the Wolfia REST API with a stable key that no longer depends on an employee's account.
  </Card>

  <Card title="Ingest questionnaires from ticketing systems" icon="ticket" href="/how-to/api-questionnaires">
    Automatically push questionnaires into Wolfia from JIRA, ServiceNow, or an email intake pipeline, authenticating as a dedicated intake service account.
  </Card>

  <Card title="Embed expert Q&A in internal tools" icon="code" href="/how-to/api-overview">
    Add Wolfia's answering to an internal portal, Slack workflow, or custom app using a service-account key scoped to exactly the role that integration needs.
  </Card>

  <Card title="Automate knowledge management" icon="book" href="/how-to/api-knowledge-upload">
    Keep your knowledge base current with a service account that uploads documents and syncs facts on a schedule, independent of any one curator's login.
  </Card>

  <Card title="Least-privilege automation" icon="lock">
    Give a read-only automation a User-role service account, and a knowledge-editing automation an Expert-role one, instead of minting keys under a human admin who has far more access than the job requires.
  </Card>
</CardGroup>

Use a personal API key only for short-lived, individual experiments. For anything shared or long-running, use a service account.

<Note>
  Service accounts are for **non-human** access (automations, MCP clients, scripts). To give your **employees** access, use [single sign-on](/how-to/sso-setup) and [SCIM provisioning](/how-to/scim-setup) instead.
</Note>

## Create a service account

<Steps>
  <Step title="Open Service accounts">
    Go to [Settings → Service accounts](https://wolfia.com/settings/service-accounts).
  </Step>

  <Step title="Create the account">
    Click **Create service account**, give it a descriptive name (for example `OpenClaw automation` or `CI questionnaire sync`), and choose a **role**.
  </Step>

  <Step title="Pick the least-privilege role">
    The service account acts with the role you assign. Grant the lowest role the automation needs:

    | Role       | Can do                                                 |
    | ---------- | ------------------------------------------------------ |
    | **User**   | Read knowledge, ask questions, run answering           |
    | **Expert** | Everything a User can, plus edit knowledge and answers |
    | **Admin**  | Full administrative access. Use sparingly              |
  </Step>
</Steps>

The new account appears with an **Active** status and **0 active keys**. It has no password and cannot log in interactively. It only acts through the API keys you issue to it.

## Issue an API key for the service account

<Steps>
  <Step title="Open API settings">
    Go to [Settings → API](https://wolfia.com/settings/api) and click **Create API key**.
  </Step>

  <Step title="Set the owner to the service account">
    In the **Owner** field, select your service account instead of "Yourself". Give the key a name and an optional expiration.
  </Step>

  <Step title="Copy the key now">
    The key is shown **once**, at creation. Copy it immediately and store it in your secret manager, because it cannot be retrieved later.
  </Step>
</Steps>

The key now carries the service account's identity and role. Its lifecycle is independent of the admin who created it.

## Use the key with the REST API

Send the key as either an `X-API-Key` header or a `Bearer` token.

<CodeGroup>
  ```bash X-API-Key theme={null}
  curl https://api.wolfia.com/v1/me \
    -H "X-API-Key: wolfia-api-..."
  ```

  ```bash Bearer theme={null}
  curl https://api.wolfia.com/v1/me \
    -H "Authorization: Bearer wolfia-api-..."
  ```
</CodeGroup>

Requests authenticate as the service account, scoped to your organization. See the [API overview](/how-to/api-overview) for the full endpoint reference.

## Use the key with MCP

Point any MCP client at Wolfia's MCP server and pass the service-account key as a bearer token. No personal OAuth login is required.

```json Claude / Cursor / Windsurf (mcp config) theme={null}
{
  "mcpServers": {
    "wolfia": {
      "url": "https://api.wolfia.com/mcp/",
      "headers": {
        "Authorization": "Bearer wolfia-api-..."
      }
    }
  }
}
```

The client connects as the service account and sees the tools allowed by its role. For the interactive, per-user OAuth flow instead, see [MCP OAuth & gateways](/how-to/mcp-server-oauth).

## Revoke access

You have two levels of control:

* **Deactivate the service account.** From [Settings → Service accounts](https://wolfia.com/settings/service-accounts), click **Deactivate**. This immediately revokes every API key bound to that account. Use it when an automation is decommissioned or a key may be compromised.
* **Deactivate or delete a single key.** From [Settings → API](https://wolfia.com/settings/api), revoke just one key while leaving the service account and its other keys active.

Either way, revoked keys stop working immediately for both the REST API and MCP. Subsequent requests return `401 Unauthorized`.

<Note>
  A service-account key keeps working even after the **person who created it** is deactivated. That is the point. To cut off a service account's access you must deactivate the account or its keys directly.
</Note>

## Good practices

* **One service account per integration.** Name it after the system it serves, so the audit trail of "who did what" stays meaningful.
* **Least privilege.** Assign the lowest role that works, and reserve Admin for genuine administrative automation.
* **Rotate keys.** Issue a new key, switch the client over, then revoke the old one. Set an expiration on keys where you can.
* **Store keys in a secret manager.** Never commit them to source control or paste them into shared docs.

## Related pages

<CardGroup cols={2}>
  <Card title="API overview" icon="code" href="/how-to/api-overview">
    Authentication, endpoints, and examples for the Wolfia REST API.
  </Card>

  <Card title="MCP server" icon="plug" href="/how-to/mcp-server">
    Connect Claude, Cursor, and Windsurf to Wolfia over MCP.
  </Card>

  <Card title="MCP OAuth & gateways" icon="shield-halved" href="/how-to/mcp-server-oauth">
    The per-user OAuth flow and gateway setup, the alternative to a service-account key.
  </Card>

  <Card title="SSO & SCIM" icon="users" href="/how-to/sso-setup">
    Give human employees access through single sign-on and directory provisioning.
  </Card>
</CardGroup>