# auth.md — Harmny You are an agent. This service supports **agent API key registration** via a short manual-review process — there is no live OAuth token endpoint. Follow the steps in order: register → wait for review → use credential → handle revocation. --- ## Step 1 — Register POST to the registration endpoint: ```http POST https://harmny.ai/api/agent/register Content-Type: application/json { "agent_name": "my-agent", "contact_email": "owner@example.com", "requested_scopes": ["frameworks", "evaluations"] } ``` | Field | Required | Description | | ------------------ | -------- | --------------------------------------------------------- | | `agent_name` | yes | Identifier for this agent instance | | `contact_email` | yes | Where the API key is sent once issued | | `requested_scopes` | yes | Subset of `scopes_supported` below | | `identity_type` | no | `"anonymous"` (default; no other types are supported yet) | Response `202 Accepted`: ```json { "registration_id": "reg_...", "status": "pending", "credential_type": "api_key", "message": "Your API key request has been received and will be processed within 1 business day. You will receive your API key at the provided contact_email.", "support": "info@harmny.ai" } ``` Registration is reviewed by a human — there is no automated token issuance. Save `registration_id` for revocation later. --- ## Step 2 — Receive the credential Your API key is emailed to `contact_email` after manual review (within 1 business day). If you don't hear back, email `info@harmny.ai` with your `registration_id`. To check on a registration by machine, POST to the claim endpoint. It reports status only and never returns the key itself: ```http POST https://harmny.ai/api/agent/claim Content-Type: application/json { "registration_id": "reg_..." } ``` Response `200 OK`: ```json { "registration_id": "reg_...", "status": "pending_manual_review", "credential_type": "api_key", "credential_delivery": "email", "message": "This registration is reviewed by a human, typically within 1 business day. The API key is sent to the contact_email given at registration; it is never returned here. If it has not arrived after 2 business days, email info@harmny.ai with the registration_id.", "support": "info@harmny.ai" } ``` A malformed `registration_id` returns `400 invalid_request`. --- ## Step 3 — Use the credential Attach the API key as a bearer token: ```http GET https://harmny.ai/api/mcp Authorization: Bearer ``` If your MCP gateway reserves the `Authorization` header for its own OAuth flow (Smithery does), send the same key as `X-Harmny-Api-Key: ` instead. The MCP endpoint supports [MCP Streamable HTTP](https://harmny.ai/.well-known/mcp/server-card.json) transport (stateless per-request). Full tool list and schemas are in that server card and in [agent-card.json](https://harmny.ai/.well-known/agent-card.json). --- ## Available Scopes | Scope | MCP Tools Unlocked | | -------------- | ------------------------------------ | | `frameworks` | `get_frameworks`, `get_competencies` | | `career_paths` | `get_career_path` | | `evaluations` | `get_employee_summary` | | `people` | `get_org_overview` | | `tasks` | `get_tasks`, `get_projects` | --- ## Errors | Code | Meaning | Action | | ----------------------- | -------------------------------- | -------------------------------------- | | `401 Unauthorized` | Missing or invalid API key | Re-register at `/api/agent/register` | | `403 Forbidden` | Key lacks required scope | Request additional scopes on a new key | | `429 Too Many Requests` | Rate limit exceeded (60 req/min) | Honor `Retry-After` header; back off | | `5xx` | Server error | Exponential backoff, retry | --- ## Revocation POST to the revocation endpoint: ```http POST https://harmny.ai/api/agent/revoke Content-Type: application/json { "registration_id": "reg_..." } ``` Response `200 OK`: ```json { "registration_id": "reg_...", "status": "revocation_requested", "message": "Revocation request received. The API key will be invalidated within 1 business day. For immediate revocation, email info@harmny.ai with subject: API Key Revocation — reg_..." } ``` This request is also reviewed manually. For immediate revocation, email `info@harmny.ai` with subject **"API Key Revocation — reg\_..."**. --- ## Machine-readable metadata Harmny publishes its agent-discovery metadata as machine-readable files under `/.well-known/`, for tooling that expects standard discovery documents rather than parsing this page: | File | What it is | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`oauth-protected-resource`](https://harmny.ai/.well-known/oauth-protected-resource) | RFC 9728 protected-resource metadata for `https://harmny.ai` (the API lives under `/api`) | | [`oauth-authorization-server`](https://harmny.ai/.well-known/oauth-authorization-server) | RFC 8414-shaped metadata, honestly empty where we have no OAuth grant flows, plus the real `/api/agent/register`, `/api/agent/claim` and `/api/agent/revoke` endpoints in its `agent_auth` block | | [`ai-catalog.json`](https://harmny.ai/.well-known/ai-catalog.json) | ARD catalog listing this guide, the agent card, the MCP server card, and the API catalog | None of these claim an OAuth authorization server that doesn't exist. They describe the same API-key flow documented above in a shape agent tooling can parse without a human reading this page first.