# Principal URL: https://docs.hanzo.ai/docs/openapi/principal > Serves an org as an economic principal: who it is, what it may pay, and which agents answer to it. Also for this capability: **API** · [MCP](https://docs.hanzo.ai/docs/mcp-tools/principal) · [SDKs](https://docs.hanzo.ai/docs/sdks) Serves an org as an economic principal: who it is, what it may pay, and which agents answer to it. > [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | -------------- | -------------------------------------- | | **Base URL** | `https://api.hanzo.ai` | | **Operations** | 7 | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | ## Specification Specification pending — no HIP in [hanzoai/hips](https://github.com/hanzoai/hips) declares `capability: principal` yet. What this capability serves is below, from the API document; what it is — the store it owns, how it meters, what it publishes — is written as a HIP under HIP-0139. ## Four surfaces | Surface | Reaches this capability as | Coverage | | -------- | ------------------------------------------------- | ------------------------------------------------------------------------- | | **REST** | `principal` at its own prefix | 7 operations | | **CLI** | — | no command reaches it yet — use HTTP or an SDK | | **SDK** | `PrincipalApi` in every published client | 7 methods | | **MCP** | tool `principal` on `https://api.hanzo.ai/v1/mcp` | 7 operations, 2 under the document's own id — ask `describe` for the rest | ## Quickstart ```bash export HANZO_API_KEY=sk-... # console.hanzo.ai → API keys ``` Then the first call — a read that needs nothing but the key. `GET /v1/principal`, operation `get_principal`: **CLI** `hanzo` has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK. **SDK** **.ts** ```ts import { Configuration, PrincipalApi } from 'hanzoai'; const api = new PrincipalApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.getPrincipal(); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import PrincipalApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = PrincipalApi(client).get_principal() ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.PrincipalAPI.GetPrincipal(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, principal_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = principal_api::get_principal(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.PrincipalApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new PrincipalApi(client).getPrincipal(); ``` **HTTP** ```bash curl https://api.hanzo.ai/v1/principal \ -H "Authorization: Bearer $HANZO_API_KEY" ``` **MCP** MCP reaches **principal** through the `principal` tool, which names its 7 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them: ```bash curl -X POST https://api.hanzo.ai/v1/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "describe", "arguments": { "op": "list_principals" } } }' ``` Answers `200` with `object` — ok. ## Endpoints | Endpoint | What it does | | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`GET /v1/principal/agents/{ref}`](https://docs.hanzo.ai/docs/openapi/principal/get-principal-agents-by-ref) | Attests which principal one of the caller's agents answers to: the org, the chain of agents that spawned it, and the same signed with the platform's key as a JWS (EdDSA) a verifier checks offline against GET /v1/principal/keys. | | [`GET /v1/principal/clearance/{id}`](https://docs.hanzo.ai/docs/openapi/principal/get-principal-clearance-by-id) | Reads one of the caller org's clearances, as it was decided. | | [`GET /v1/principal/clearance`](https://docs.hanzo.ai/docs/openapi/principal/get-principal-clearance) | Lists the caller org's clearances, newest first, 200 at most; a payee narrows them. | | [`POST /v1/principal/clearance`](https://docs.hanzo.ai/docs/openapi/principal/post-principal-clearance) | Decides whether the caller's org may pay another org, BEFORE the payment: what must happen first, what must be withheld and why, what must be reported, by whom and when, and how the payment may settle net of withholding. | | [`GET /v1/principal/keys`](https://docs.hanzo.ai/docs/openapi/principal/get-principal-keys) | Publishes the keys attestations are signed with, as a JSON Web Key Set (RFC 7517; Ed25519 keys as RFC 8037 writes them). | | [`GET /v1/principal/statements/{id}`](https://docs.hanzo.ai/docs/openapi/principal/get-principal-statements-by-id) | Reads whether one statement the platform signed about an agent still stands: live, expired, or revoked and when. | | [`GET /v1/principal`](https://docs.hanzo.ai/docs/openapi/principal/get-principal) | Returns the caller's org as an economic principal, composed from the apps that own each fact: its legal entity and founders' identity verification (company), the W-9 or W-8 it certified (tax), its wallets (wallet), the agents that answer to it — spawned ones with the agent that spawned them — (agents), its screening against the OFAC, UN, EU and UK sanctions lists and the embargoed jurisdictions, run now, and what it still lacks to pay and be paid. | --- [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)