Skip to main content

​
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.
Only organization administrators can create, view, or deactivate service accounts and issue keys against them.

​
Use cases

Connect MCP clients without personal login

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.

CI/CD and scheduled automations

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.

Ingest questionnaires from ticketing systems

Automatically push questionnaires into Wolfia from JIRA, ServiceNow, or an email intake pipeline, authenticating as a dedicated intake service account.

Embed expert Q&A in internal tools

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.

Automate knowledge management

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.

Least-privilege automation

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.
Use a personal API key only for short-lived, individual experiments. For anything shared or long-running, use a service account.
Service accounts are for non-human access (automations, MCP clients, scripts). To give your employees access, use single sign-on and SCIM provisioning instead.

​
Create a service account

1

Open Service accounts

Go to Settings → Service accounts.
2

Create the account

Click Create service account, give it a descriptive name (for example OpenClaw automation or CI questionnaire sync), and choose a role.
3

Pick the least-privilege role

The service account acts with the role you assign. Grant the lowest role the automation needs:
RoleCan do
UserRead knowledge, ask questions, run answering
ExpertEverything a User can, plus edit knowledge and answers
AdminFull administrative access. Use sparingly
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

1

Open API settings

Go to Settings → API and click Create API key.
2

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.
3

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.
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. 
curl https://api.wolfia.com/v1/me \
  -H "X-API-Key: wolfia-api-..."
Requests authenticate as the service account, scoped to your organization. See the 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.
Claude Windsurf (mcp config)
{
  "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.

​
Revoke access

You have two levels of control:
  • Deactivate the service account. From 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, 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.
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.

​
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.

API overview

Authentication, endpoints, and examples for the Wolfia REST API.

MCP server

Connect Claude, Cursor, and Windsurf to Wolfia over MCP.

MCP OAuth & gateways

The per-user OAuth flow and gateway setup, the alternative to a service-account key.

SSO & SCIM

Give human employees access through single sign-on and directory provisioning.