Skip to main content

The Ask API

The /ask API is the pre-flight check that agents use before running a tool or action: given an action slug and optional context, it returns whether the caller is authorized, plus a human-readable reason. The response is structured for easy use inside an LLM tool loop — an agent can call /ask first, and branch on the result.

Check capability​

POST /orgs/{orgId}/api/v1/agents/ask

Verifies whether the calling agent is authorized to perform a specific action within a given context.

Request body​

FieldTypeDescription
actionstringRequired. The permission or action slug (e.g., document.read).
contextobjectOptional data required for the check (e.g., {"id": "123"}).

Example request​

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/agents/ask \
  -H "Authorization: Bearer agent_token_abc" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "document.read",
    "context": {
      "id": "doc_99"
    }
  }'

Example response​

{
  "allowed": true,
  "action": "document.read",
  "context": {
    "id": "doc_99"
  },
  "reason": "Agent has authorized capability for 'document.read'.",
  "audit_id": "8f3a1b2c4d5e6f7a"
}

Self inspection​

GET /orgs/{orgId}/api/v1/agents/me

Lets an agent look up its own identity, capabilities (roles), and organization environment.

Example response​

{
  "identity": {
    "id": "agt_91827364",
    "type": "agent",
    "organization": "Acme Corp"
  },
  "capabilities": [
    "ROLE_RESEARCHER",
    "ROLE_DATA_READER"
  ],
  "workspace": {
    "slug": "acme",
    "api_base": "/orgs/acme-corp/api/v1/"
  }
}

Integration strategy​

Use /ask inside your tool definitions. Before the agent calls a tool like get_document(id), it should run a pre-flight check via /ask. If allowed is false, use the reason field to inform the user or trigger a delegation/JIT request.

Using the Python SDK​

The lumoauth package exposes the Ask API via ask(), is_allowed(), and get_identity():

pip install lumoauth
from lumoauth import LumoAuthAgent

agent = LumoAuthAgent()   # reads env vars
agent.authenticate()

# Pre-flight check before executing a tool
result = agent.ask("document.read", context={"id": "doc_99"})
if result["allowed"]:
    # proceed with the tool call
    ...
else:
    print(f"Denied: {result['reason']}")

# Shorthand
if agent.is_allowed("document.read", {"id": "doc_99"}):
    ...

# Self-inspection
identity = agent.get_identity()
print(identity["capabilities"])   # e.g. ["ROLE_RESEARCHER", "ROLE_DATA_READER"]
print(identity["workspace"])      # e.g. {"slug": "acme", "api_base": "/orgs/acme-corp/api/v1/"}