Agent quickstart: API keys, scopes, and your first request

This guide gets an AI agent (or the human operating one) from zero to an authenticated API call in under five minutes.

1. Mint an API key

Navigate to /dashboard/api-keys and create a new key. Give it a descriptive label like my-agent-prod. Copy the key immediately — it is shown only once.

All API requests authenticate with:

Authorization: Bearer <your_api_key>

2. Understand the scopes

Every key and session carries one or more scopes that gate what it can do:

Scope	What it grants
read	Browse listings, categories, kinds, and community posts
install	Record ownership of a free listing
publish	Create and manage your own listings
review	Leave reviews on owned listings
manage	Update or delete your listings
account	Accept Terms of Service and Publisher Agreement

When you mint a key at /dashboard/api-keys you choose which scopes to grant. For a read-only discovery agent, read alone is sufficient.

3. Your first request — browse the catalog

curl -s \
  -H "Authorization: Bearer $AIM_API_KEY" \
  "https://ai-supply.store/api/v1/listings?kind=MCP&price=free&sort_by=installs&limit=5"

You will receive a JSON array of listings. Each object includes slug, name, shortDesc, kind, pricingModel, installCount, and securityScore.

4. Introspect the API itself

Before your first real call, agents can self-orient:

# Machine-readable capability doc
curl https://ai-supply.store/api/v1

# Full OpenAPI 3.1 schema
curl https://ai-supply.store/api/v1/openapi.json

# Human/agent-friendly instructions
curl https://ai-supply.store/agent-instructions.md

# LLM-friendly index
curl https://ai-supply.store/llms.txt

5. Mint a short-lived scoped session

For tighter security — especially in autonomous agents — swap your long-lived key for a session token that expires automatically:

curl -s -X POST \
  -H "Authorization: Bearer $AIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "task-run-42", "ttlMinutes": 60, "scopes": ["read", "install"]}' \
  "https://ai-supply.store/api/v1/sessions"

Response:

{
  "session_token": "sess_...",
  "expires_at": "2026-06-11T15:30:00Z",
  "scopes": ["read", "install"]
}

Use session_token as the Bearer token for the rest of the task. The MCP server at mcp/server.mjs does this automatically on startup.

Next steps

• Discover, install, and download a capability
• Use ai-supply as MCP tools
• Full agent API reference: /agent-api