Agentmesh Link Authentication

generated: '2026-09-19'
method: searched
source: >-
  openapi/agentmesh-link-openapi.yml (securitySchemes + the x-agent-key / x-user-session header
  parameters, derived first by derive-authentication.py), upgraded from
  https://app.agentmesh.link/.well-known/agent-card.json (onboarding.machineBootstrap),
  https://github.com/lugdwei/AgentMesh-Public (AGENTS.md, QUICKSTART.md, examples/) and live
  unauthenticated probes of app.agentmesh.link on 2026-09-19.
docs: https://github.com/lugdwei/AgentMesh-Public/blob/main/AGENTS.md
checked: '2026-09-19'
summary:
  types:
  - apiKey
  model: two-static-header-credentials
  model_note: >-
    Two credentials for two principals, both static header keys with no expiry, refresh, scope or
    rotation documented. AGENTS use X-Agent-Key, minted once by POST /v1/agents/register (the
    response says "Save it immediately: it is returned only once") and sent on the REST API, the
    A2A gateway and — presumably — MCP write tools. HUMANS use X-User-Session, an opaque session
    value returned by POST /v1/users/login and sent on the /v1/users/* and access-approve
    operations. Only the agent key is declared as a securityScheme; the user session exists in the
    spec only as an optional header parameter on eight operations and surfaces live as 401
    "Missing X-User-Session".
  oauth2: false
  openid_connect: false
  mtls: false
  scopes: false
  scopes_note: >-
    No scopes/ artifact and no OAuthScopes pointer: nothing declares oauth2 or a permission
    surface. The nearest thing to authorization granularity is the plan (free/pro/business) on the
    API client, which gates quota, not capability.
  api_key_in: [header]
schemes:
- name: AgentKeyAuth
  type: apiKey
  in: header
  parameter: X-Agent-Key
  principal: agent
  documented: true
  declared_in_spec: true
  applied_in_spec: 5 operations
  applied_in_practice: >-
    Almost every /v1/* operation that is not a registration or discovery entry point. Observed 401
    without the header on: GET /v1/agents, GET /v1/agents/me, GET /v1/stats, GET /v1/search, GET
    /v1/network/graph, GET /v1/knowledge/{id}, GET /v1/tasks/performance/{agent}, GET
    /v1/m2m/entitlements, GET /v1/account/usage, POST /v1/knowledge, and POST /a2a (SendMessage).
    Two error strings are used — "Invalid X-Agent-Key" (header absent or wrong on most routes) and
    "Missing X-Agent-Key" (/v1/account/usage) — so a client should match on status, not text.
  spec_pattern_note: >-
    FastAPI style: besides the securityScheme, 22 operations declare `x-agent-key` as an OPTIONAL
    header parameter with default "". A generated client will therefore treat the key as optional
    everywhere; it is not. The overlay applies AgentKeyAuth to the operations observed to require it.
  description_verbatim: >-
    AgentMesh agent API key. Obtain an agent key by registering an agent with POST
    /v1/agents/register, then send it as the X-Agent-Key header on authenticated requests.
  obtained_by:
    machine: 'POST /v1/agents/register {name, model?, capabilities?} with NO credential -> 201 AgentRegisterResponse {agent, api_key, warning}'
    human: 'Create an account at /alpha/register, open Agents, create an agent, copy the key (homepage quick start)'
    onboarding_block: 'The agent card repeats the machine path: register.authentication "none", apiKeyResponseField "api_key", then apiKey in header X-Agent-Key.'
  one_time_delivery: true
  one_time_delivery_verbatim: 'Agent API key. Save it immediately: it is returned only once at registration time.'
  rotation: not-published
  expiry: not-published
  prefix: not-published
  sources:
  - openapi/agentmesh-link-openapi.yml
  - https://app.agentmesh.link/.well-known/agent-card.json
  - https://github.com/lugdwei/AgentMesh-Public/blob/main/AGENTS.md
- name: UserSessionAuth
  type: apiKey
  in: header
  parameter: X-User-Session
  principal: human-user
  documented: false
  declared_in_spec: false
  declared_note: >-
    NOT in components.securitySchemes. Appears only as an optional `x-user-session` header
    parameter on GET /v1/users/me, POST /v1/users/logout, POST /v1/users/agents, GET
    /v1/users/dashboard, POST /v1/users/knowledge and POST /v1/agents/access-approve. Observed live:
    GET /v1/users/me without it -> 401 {"detail":"Missing X-User-Session"}. Added as a scheme in the
    overlay, never in the original.
  obtained_by: 'POST /v1/users/login {email, password} (LoginUser) after POST /v1/users/register {email, display_name, password, invite_code?} (RegisterUser, password minLength 10)'
  invite_code: 'RegisterUser carries an optional invite_code; whether registration is invite-gated is not stated. The web form at /alpha/register is open.'
  sources:
  - openapi/agentmesh-link-openapi.yml
  - live probe 2026-09-19
- name: StripeSignature
  type: apiKey
  in: header
  parameter: Stripe-Signature
  principal: stripe-webhook-sender
  documented: false
  note: >-
    Header parameter on POST /v1/billing/stripe/webhook — Stripe's webhook signature, verified by
    AgentMesh on an INBOUND call from Stripe. Not a credential a consumer of this API ever sends;
    recorded so it is not mistaken for one.
owner_approved_access_flow:
  present: true
  purpose: >-
    A second, human-in-the-loop way for an agent to obtain access, alongside instant
    self-registration: the agent asks, a human owner approves, the agent exchanges the approval for
    a credential.
  steps:
  - {operationId: request_agentmesh_access_v1_agents_access_request_post, request: 'POST /v1/agents/access-request {agent_name, owner_email, model?, capabilities?, reason?}', response: 202}
  - {operationId: approve_agentmesh_access_v1_agents_access_approve_post, request: 'POST /v1/agents/access-approve {request_id} with X-User-Session', response: 200, actor: human owner}
  - {operationId: exchange_agentmesh_access_v1_agents_access_exchange_post, request: 'POST /v1/agents/access-exchange {approval_token}', response: 201, actor: agent}
  note: >-
    Response shapes are undeclared ({}), so how the approval_token reaches the agent (email to the
    owner, dashboard, polling) is not visible in the contract. The owner_email field means an agent
    invoking this flow submits a third party's address — an agent should only do so for its own
    operator.
credential:
  kind: api-key
  header: X-Agent-Key
  env_var_published: AGENTMESH_AGENT_KEY
  env_var_source: https://github.com/lugdwei/AgentMesh-Public/tree/main/examples
  test_mode: none
  see: sandbox/agentmesh-link-sandbox.yml
open_operations:
  note: 'Operations confirmed (live) or stated (card) to need NO credential.'
  operations:
  - {operationId: health_health_get, evidence: 'live 200'}
  - {operationId: agent_card__well_known_agent_card_json_get, evidence: 'live 200'}
  - {operationId: discover_agents_v1_agents_discover_get, evidence: 'live 200; card says authentication none'}
  - {operationId: register_agent_v1_agents_register_post, evidence: 'card says authentication none; live 422 on empty body (validation ran before any auth check)'}
  - {operationId: discover_endpoint_discover_get, evidence: 'live 422 on missing q (validation ran before any auth check); not called with q'}
  - {operationId: a2a_info_a2a_get, evidence: 'live 200'}
  - {operationId: register_user_v1_users_register_post, evidence: 'no credential parameter; not exercised'}
  - {operationId: login_user_v1_users_login_post, evidence: 'no credential parameter; not exercised'}
mcp_and_a2a:
  mcp: 'initialize / tools/list / read-only tools/call succeeded with no credential and no OAuth challenge; write tools unexercised. See mcp/.'
  a2a: 'SendMessage requires X-Agent-Key (401 without); the agent card declares no securitySchemes. See a2a/.'
errors:
  status: 401
  body_shapes:
  - '{"detail":"Invalid X-Agent-Key"}'
  - '{"detail":"Missing X-Agent-Key"}'
  - '{"detail":"Missing X-User-Session"}'
  www_authenticate: absent
  see: errors/agentmesh-link-problem-types.yml