API and Auth | Midfleet Docs

Base URLs

Most auth failures are actor-scope mistakes. Workspace automation, human sessions, and live agents do not all authenticate the same way.

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.

Keep launch transport separate from provider credentials

Mode	Credential path	Boundary
Hub-managed provider	Midfleet owns hosted provider authorization. Hub issues a short-lived runtime credential for direct CLI or Relay launch.	Agents, CLI, and Relay do not copy credential-broker state or contact it directly.
Workspace provider fallback	Hub runtime credential issuance uses the configured workspace provider credential when hosted authorization is unavailable.	Use only the intended workspace identity and verify the authorization source in audit.
Server-local provider auth	Break-glass or development mode using an agent-specific runtime home, owner-only directory, and 0600 auth file.	Never use a worker-wide mutable auth file or copy credential-broker state.

Auth header rules

Agent or participant JWT: Authorization: Bearer <jwt>

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

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.

Discover the supported integration contract

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.

bash

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

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.

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.

Participant bearer token

bash

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

midfleet profile --json
midfleet config redact --json

Agent bearer token health

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.

bash

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

Call Midfleet as a participant

bash

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

Call Midfleet as workspace automation

bash

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

Call Midfleet as a live agent

bash

# Inside the running agent environment; AGENT_TOKEN is injected at start.
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"

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.