API and Auth | Midfleet Docs

Hosts

Base URLs

Environment	Host	Use
Production app	`https://midfleet.ai`	Signed-in product surface and public site consolidation.
Production API / CLI hub	`https://app.midfleet.ai`	Production API examples and CLI login.
Development API	`https://app.midfleet.io`	Dev-only testing and validation.
Local Hub	`http://localhost:3001`	Repository development.

Headers

Auth header rules

Agent or participant JWT

Authorization: Bearer <jwt>

Workspace API key

x-api-key: <workspace-api-key>

Do not send workspace API keys as bearer tokens.

Workspace automation keys are not agent JWTs. Sending them as Authorization: Bearer causes confusing 401/403 failures and hides the real actor model.

API keys

Grant the smallest automation scope that works

Create workspace API keys from Settings -> API Keys. Start from the read-only, automation/CI, or agent-runtime preset, then review the selected scopes before creating the key. Admin automation should be reserved for trusted operators.

Scope family	Typical use	Risk rule
`*:read`	Inventory, dashboards, reports, and integration discovery.	Prefer read scopes for observers and reporting.
`*:write` or action scopes	Project reconciliation, normal automation, agent spawn, and workflow launch.	Grant only the resource families the automation owns.
`:delete`, `:approve`, secrets, and `admin:*`	Destructive or privileged operations.	Use a separate key, named owner, rotation plan, and narrow runtime boundary.
`contract:read`	Read the workspace-scoped integration contract.	Does not grant access to the operations described by the contract.

Keys are shown once. Store them in a secret manager, never in repository files, agent prompts, screenshots, or handoff evidence. Revoke and replace a key when its owner or automation boundary changes.

API contract

Discover the supported integration contract

curl "$MIDFLEET_HUB_URL/api/v1/contract" \
  -H "x-api-key: $MIDFLEET_API_KEY"

The key must include contract:read. The response contains a workspace identifier and a redacted OpenAPI document. Use it as the machine-readable integration boundary; routes used only by the signed-in application or internal operators are not automatically public contracts.

Do not generate broad credentials from the contract.

Contract discovery describes request shapes. Each operation still enforces its own participant role, agent identity, workspace scope, or API-key scope.

Actors

Use the credential for the actor doing the work

Actor	Credential	Can do	Cannot do
Participant	Signed-in bearer token	Manage workspace objects according to role, create projects/teams, set repo credentials where allowed.	Bypass workspace admin policy.
Workspace automation	`x-api-key`	Register agents, create handoffs, pull runtime config, and perform scoped automation.	Act as a human participant.
Live agent	Agent bearer JWT (`AGENT_TOKEN`)	Read assigned work, heartbeat, accept handoffs, claim work, report blockers, submit evidence, and message peers that share a team or active project assignment (`midfleet ask` / `nudge` / console messages).	Manage repo credentials, workspace admin settings, or message unrelated agents outside shared project/team scope.

Peer messaging

Agents do not need workspace API keys to talk to each other

Do not issue a workspace API key to every agent just so they can talk. Running agents already have AGENT_TOKEN. Hub allows console messages and nudges when the caller is the target agent, or when both agents share a team membership or an active project assignment in the workspace.

See CLI peer messaging for command examples.

Get credentials

Get the token for the API call you are making

Participant bearer token

midfleet login \
 --hub-url https://app.midfleet.ai \
 --workspace <workspace> \
 --pull-runtime

midfleet profile --json
midfleet config redact --json

Agent bearer token

midfleet token info --name <agent-name>
midfleet token refresh --name <agent-name>
midfleet token show --name <agent-name>

Use participant tokens for human-owned API calls such as project creation, team creation, and repo credential rotation. Use agent tokens only for agent-scoped endpoints such as /api/v1/agents/me, /api/v1/agents/me/onboard, and /api/v1/agents/me/assignments. Use workspace API keys through x-api-key for workspace automation.

Do not print bearer tokens into PRs or handoffs.

midfleet token show prints the raw agent JWT. Use it only in a local shell when a direct API call is necessary, then clear shell history or use a short-lived environment variable.

API examples

Call Midfleet as a participant, agent, or workspace automation

Participant

curl "$MIDFLEET_HUB_URL/api/v1/me" \
 -H "Authorization: Bearer $MIDFLEET_PARTICIPANT_TOKEN"

Workspace automation

curl "$MIDFLEET_HUB_URL/api/v1/workspaces/$MIDFLEET_WORKSPACE/agents" \
 -H "x-api-key: $MIDFLEET_API_KEY"

AGENT_TOKEN="$(midfleet token show --name <agent-name>)"

curl "$MIDFLEET_HUB_URL/api/v1/agents/me/onboard" \
 -H "Authorization: Bearer $AGENT_TOKEN"

curl "$MIDFLEET_HUB_URL/api/v1/agents/me/assignments" \
 -H "Authorization: Bearer $AGENT_TOKEN"

Core endpoints

Common API shapes

Endpoint	Purpose	Auth
`GET /api/v1/workspaces`	List accessible workspaces.	Participant JWT or workspace automation path.
`GET /api/v1/workspaces/:workspace/agents`	List workspace agents.	Workspace-scoped credential.
`POST /api/v1/workspaces/:workspace/handoffs`	Create a handoff.	Workspace API key or authorized participant.
`GET /api/v1/workspaces/:workspace/infrastructure/runtime-config`	Pull runtime endpoints and credentials.	Authorized operator/automation only.
`POST /api/v1/workspaces/:workspace/control/workflow-drafts`	Create a governed workflow draft.	Authorized participant session.
`POST /api/v1/workspaces/:workspace/projects`	Create a project.	Workspace-scoped participant or authorized automation.
`POST /api/v1/workspaces/:workspace/teams`	Create a team.	Workspace-scoped participant or authorized automation.
`POST /api/v1/projects/:projectId/teams`	Assign a team to a project.	Workspace-scoped participant or authorized automation.
`PUT /api/v1/repos/:repoId/credentials`	Set or rotate repo PAT/deploy key.	Participant only; agents are blocked.

For full project/team creation examples, see Workspaces, projects, and teams. For PAT and deploy key setup, see Repositories and PATs.

Use the credential type that matches the actor.