Authentication

Authenticate with an API key using the standard HTTP Authorization header. Keys are scoped to a tenant and workspace.

Headers

Store your API key in a shell variable and reference it in the Authorization header:

export MEDFLOW_API_KEY='your-api-key'

curl "https://api-staging.medflow.care/v1/me" \
  -H "Authorization: Bearer $MEDFLOW_API_KEY" \
  -H "Content-Type: application/json"

Any optional scopes on the key narrow what it can do.

Tenant and workspace

Every route is scoped by your key, which belongs to one workspace within one tenant, so you never pass a tenant or workspace id in a request. The {triggerId} in a path like /v1/triggers/{triggerId} is always resolved inside that workspace, and a request can never reach another tenant’s data.

If you work across more than one workspace, request a separate key for each. A key is never shared between workspaces, so each one carries its own workspace context and its own scopes.

Getting a key

Contact us with your tenant, workspace, and intended use (for example web triggers, search, or webhooks).
We issue an API key with the scopes you need and share the secret once.
Store the secret in your secrets manager (or export MEDFLOW_API_KEY=… for local curl). Treat it like a password.

MedFlow stores a hash of the secret, not the secret itself. Audit events record the key id and name, not the secret.

To rotate or revoke a key, use the same contact form.

Verify a key

Call GET /v1/me to confirm a key is valid and see the context it resolves to. It needs no scope, so it works with any key, and it is the quickest way to check you are pointed at the right tenant, workspace, and environment before building anything else.

curl "https://api-staging.medflow.care/v1/me" \
  -H "Authorization: Bearer $MEDFLOW_API_KEY"

A valid key returns 200 with its context. A missing, invalid, or revoked key returns 401.

{
  "tenantId": "<uuid>",
  "workspaceId": "<uuid>",
  "keyId": "<uuid>",
  "keyName": "<string>",
  "scopes": ["<string>"],
  "environment": "staging | production"
}

Scopes

If a key has no scopes listed, it receives full access for that tenant (subject to product entitlements).

Scope	Allows
`search:read`	Execute Find search and count
`queries:read`	List and get queries
`queries:write`	Create, update, delete queries
`diagrams:read`	List and get diagrams (read-only, authored in the UI)
`triggers:read`	List and get triggers
`triggers:write`	Create, update, delete triggers
`runs:read`	Get, list, and aggregate run status
`runs:write`	Start, cancel, pause, and resume runs
`webhooks:read`	List and get webhook endpoints
`webhooks:write`	Create, update, delete webhook endpoints

Missing scope returns 403 with a clear error code.

A typical Quickstart key needs at least runs:write and runs:read (and often triggers:read).

Rotation and revocation

Rotate by requesting a new key, updating callers, then asking MedFlow to revoke the old key.
Revoked keys fail auth immediately (401).
The key’s lastUsedAt updates on every successful call, so you can spot keys that are no longer in use.

Rate limits

Rate limits apply per API key. When you exceed the limit, the API returns 429. Back off and retry with jitter.

Error responses

{
  "error": "<string>",
  "code": "<string>",
  "requestId": "<string>"
}

Status	Meaning
`401`	Missing, invalid, or revoked key
`403`	Valid key, insufficient scope or permission
`404`	Resource not found in this tenant
`409`	Conflict (for example, idempotency mismatch)
`429`	Rate limited

See API overview and Security.