API and keys

Who the API is for

The v1 API is for scripts, dashboards of your own and pipelines that read or change the data of one Spellwarden organisation: list skills and MCP servers, start scans, read findings, start eval runs, read runtime traces, export policy packs. It is on the Team and Enterprise plans, and a trial of Team counts. Some routes need Enterprise, such as everything about the private registry.

A key reaches exactly one organisation. Someone who works in several organisations creates a key in each. The API answers in JSON, and every route lives under one base address, shown below. The same tree is also what the Claude connector and other MCP clients use, acting as the person who approved them, as the connector guide describes.

Keys are created and revoked in the dashboard. An API key can list the keys of its organisation and cannot create or revoke one, so a script cannot widen its own access.

Key types

A key has one access level, chosen when it is created and never changed afterwards. There are four. An organisation can have 20 read or write keys together, 200 CI keys and 20 ingest keys at the same time; each kind counts against its own limit. Revoked keys do not count.

No key holds the policy:admin scope, which only owners and managers hold in the dashboard. Accepting a critical or high finding, changing the registry's policy or an organisation rule, and promoting a finding to a rule are therefore dashboard actions. A request for one of them with a key is answered permission_denied. A write route called with a read key is answered write_access_required.

Ingest keys are for runtime traces and have their own guide: Runtime traces and sessions. An ingest key sent to a v1 route or the MCP endpoint is refused with ingest_credential_not_allowed.

Create and revoke a key

Only owners and managers can create or revoke keys. Other roles can see the list. Creating a key in an organisation that is read-only for lack of billing is refused until billing is added.

1. Open Settings and then API keys in the dashboard.
2. Select Create API key. Give the key a name of 1 to 64 characters that tells you where it is used, and choose the access: Read, Read and write, CI (service account) or Ingest.
3. Select Create API key in the dialog. The result shows the key once, with the note that it will not be shown again. Copy it, then select Done.
4. Store the key in the secret store of the tool that will use it, such as the secrets of your pipeline.

A key starts with swk_ and is 44 characters long. The fixed prefix lets secret scanners recognise a leaked key. Spellwarden keeps a hash of the key, the prefix and the last four characters, never the value, so it cannot show the key again. If a key is lost, create another and revoke the old one.

The list shows each key's name, access, last four characters, creator, creation date and last use. The last-use time is updated at most once every 60 minutes, so a key used a minute ago may still show an older time.

To revoke a key, select Revoke next to it and confirm. Scripts that use it stop working at once, with api_key_revoked. The key stays in the list under Revoked keys. Creating and revoking are written to the audit log. If creating a key answers api_key_limit, the organisation has reached the limit of that key type; revoke one that is no longer used.

Authenticate a request

The base address of the API is https://dash.spellwarden.ai/api/v1. Every route in the table below is relative to it. Send the key in the x-api-key header, or as a bearer token in the Authorization header. When both are present, x-api-key is used.

A first request lists the organisation your key reaches. Keep the key in an environment variable rather than in the command:

curl -H "x-api-key: $SPELLWARDEN_API_KEY" https://dash.spellwarden.ai/api/v1/orgs

The answer has an orgs list with the organisation's URL name (slug), name, plan, billing state and whether it can be reached, and a caller object that says the caller is an API key and its access. The URL name is the value you put in the paths below where they show {slug}. To read one organisation, call /api/v1/orgs/<your-organisation>: it adds the member count and whether single sign-on is on.

The same call without a key shows what a refusal looks like. This was run once without any credential, and the answer is unchanged apart from its request id being shortened to the field's name:

curl -i https://dash.spellwarden.ai/api/v1/orgs
HTTP/2 401
content-type: application/json
www-authenticate: Bearer resource_metadata="https://dash.spellwarden.ai/.well-known/oauth-protected-resource"

{"error": "api_key_missing", "message": "This request has no API key.", "request_id": "<request id>"}

The v1 routes

The routes below are those registered in the backend's v1 tree. Paths are relative to the base address; {slug} is the organisation's URL name and {id} the identifier a list route returned. The scope is what the key needs: a read key holds org:read, apikey:read and data:read, a read and write key adds data:write, and a CI key holds org:read and ci:run. Routes that need ci:run reject every other key with ci_key_required.

A list route answers one page and a cursor; pass the cursor back as the cursor query parameter to get the next page. The field is called cursor or next_cursor depending on the route. Every call of a read-only organisation is refused with subscription_required, reads included.

Organisation and keys

Skills

MCP servers

Scans and findings

Registry

Rules, policy packs and the trust score

Evals and exports

Runtime, repositories and the catalog

CI and the MCP endpoint

Errors

An error answers with a JSON body of three fields: error, a short code that a program can match on; message, one plain sentence; and request_id. Some codes add fields, such as the name of the field that was wrong. The same id is in the X-Request-Id response header. Match on the code, not on the message, and quote the request id when you write to hello [at] spellwarden [dot] ai about a failed call.

Rate limits

The API allows 300 requests a minute for each key. The count starts after the key is checked, so a refused key is not counted, and each key has its own count: two keys of one organisation do not share it. When a key is over the limit the answer is 429 with the code rate_limited and a Retry-After header with the number of seconds until the window ends. Wait that long before the next call.

Some routes have a lower limit of their own, counted for the organisation or the key:

The CI routes and ingest have their own limits, described in their guides. Eval runs also count against the organisation's monthly allowance, which the evals guide covers.

CI tokens

A CI token is the credential of connected CI. It lasts 15 minutes, starts with swt_, and is minted by Spellwarden from the identity token that the code host gives the pipeline run. The pipeline exchanges one for the other at the start of a run, so it never stores a secret. A CI token is never created or listed under Settings, and it has no entry in the key list.

The token is bound to one repository and to the one pipeline run it was minted for, and it holds the same two scopes as a CI key: org:read and ci:run. It reaches the three CI routes of the table above and the organisation read, and nothing else. On any other route it is refused with permission_denied, on the MCP endpoint with ci_credential_not_allowed, and on a repository it is not bound to with scope_mismatch. The GitHub Action and the GitLab component do the exchange for you.

A CI key is the fallback for a pipeline that cannot present an identity token. Create it with the access CI (service account); it holds the same scopes and reaches the same routes, and the value is a swk_ key like any other. The setup of both, and what a connected run does, is in Scan in CI with GitHub or GitLab.

The reverse also holds: a read or write key, or a connector, that calls a CI route is refused with ci_key_required. CI credentials do one job, and the keys that read data cannot be used to upload scans as a pipeline.

The MCP endpoint

Spellwarden's MCP server is part of the same tree, at https://dash.spellwarden.ai/api/v1/mcp. It takes POST requests only; a GET is answered 405. Claude and other MCP clients usually connect with a sign-in and an approval, and the connector guide covers that route: Spellwarden connector for Claude.

A client that cannot sign in can use a read or a read and write key instead. The tools that only read work with either; a tool that changes data needs a read and write key and otherwise answers write_access_required. For Claude Code the dashboard's Connect an MCP client page shows this command, to run with your key in place of YOUR_API_KEY:

claude mcp add --transport http spellwarden https://dash.spellwarden.ai/api/v1/mcp --header "Authorization: Bearer YOUR_API_KEY"

CI keys, CI tokens and ingest keys are refused at this endpoint.

Related guides

• Spellwarden connector for Claude
• Scan in CI with GitHub or GitLab
• Runtime traces and sessions
• Organisations, members and roles