Create an API key for CI

Let an agent in your CI pipeline or on a server work with Marshal, with no browser and no person signed in. An organization API key connects any MCP client, such as Claude Code in a CI job, to the Marshal MCP server. The client can then read runs, launch deputy missions, and answer questions, with the role you give the key.

Before you start

You are an organization owner or admin. Only they can create, list, and revoke keys.
You have the CLI installed and signed in. See Install the CLI and sign in.
MCP access is on for your organization: organization menu, Organization settings, General, card MCP access, switch Allow MCP access.
For a key that launches runs or spaces: switch Require approval for every launch off in the same card. A key cannot answer a confirmation prompt, so while approval is required it can read and answer, but not launch.

Steps

Make sure the CLI points at the organization the key is for: marshal org current. Switch with marshal org switch <slug> if needed.
Create the key. Give it a name that says where it runs:
```
marshal api-key create ci-agent --role member
```
--role is member (the default) or admin. Pick the smallest role the job needs.

A key can use the Read, Launch and Answer MCP permissions by default. Add --mcp-scopes read,launch,answer,manage to choose them yourself; manage and admin unlock the tools that change spaces, deputies and org settings, and admin needs --role admin.
Copy the key. It starts with marshal_ and is shown only once.
Store it as a secret in your CI system, for example a repository secret named MARSHAL_API_KEY.

In the CI job, add Marshal to the MCP client and send the key as a bearer token:


claude mcp add --transport http marshal https://marshal.example.com/mcp \
  --header "Authorization: Bearer $MARSHAL_API_KEY"

The full client setup is in Connecting an AI agent (MCP).

How a key acts

A key belongs to one organization and has its own role. It is not a person.
A run it starts is credited to the person who created the key.
It reaches only what the organization owns, never a member’s private deputy or manifest.
A key works with the Marshal MCP server at /mcp.

What you should see

After create: ✓ API key created., a reminder to copy it now, then the key on its own line.
marshal api-key list shows the key with its ID, name, role, when it was last used, and when it was created.
In the audit log, key use shows as events with severity sensitive.

Revoke a key


marshal api-key revoke <key-id>

The ID is the first column of marshal api-key list. A prefix of at least 4 characters is enough. It prints ✓ Revoked. The next call with that key is refused with “this API key was revoked”.

Give your CI agent work to do: create a deputy and a mission owned by the organization, so the key can launch it.