> ## Documentation Index > Fetch the complete documentation index at: https://docs.humanos.tech/llms.txt > Use this file to discover all available pages before exploring further. # Register Agent > Verify the agent's confinement evidence, grade its assurance rung, assign its DID and write its genesis: a platform-signed ACTOR_REGISTERED and an organization-signed AFFILIATION linking the agent to you Every key you hold proves it is held: the evidence carries `proof`, a `via-reg+jwt` signed by the key over the challenge (v0.3 §16.5) Evidence that cannot be checked degrades the rung: the response reports `granted` and, when it differs from what the evidence claimed, `degradedFrom`. Evidence that is wrong is refused with its code Idempotent by key: registering the same key again returns the existing agent (`existing: true`) rather than a second identity ## OpenAPI ````yaml /versions/2026-10-16.yaml post /agents/register openapi: 3.1.0 info: title: Humanos API description: Humanos API version: '1.0' contact: {} servers: - url: https://api.humanos.tech security: [] tags: - name: humanosApp description: '' paths: /agents/register: post: tags: - Agents summary: Register Agent description: >- Verify the agent's confinement evidence, grade its assurance rung, assign its DID and write its genesis: a platform-signed ACTOR_REGISTERED and an organization-signed AFFILIATION linking the agent to you Every key you hold proves it is held: the evidence carries `proof`, a `via-reg+jwt` signed by the key over the challenge (v0.3 §16.5) Evidence that cannot be checked degrades the rung: the response reports `granted` and, when it differs from what the evidence claimed, `degradedFrom`. Evidence that is wrong is refused with its code Idempotent by key: registering the same key again returns the existing agent (`existing: true`) rather than a second identity operationId: agents_register parameters: - $ref: '#/components/parameters/ApiVersion' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RegisterAgentBody' responses: '201': description: Returns the agent, its granted rung, and its genesis key id. content: application/json: schema: $ref: '#/components/schemas/AgentRegistrationEntity' '400': description: >- The body is malformed, or the evidence was refused, its code first in the message: the nonce is unknown, expired, already spent or another organization's (`attestation_nonce_invalid`), the key is not shown to be held (`pop_invalid`), or the evidence is wrong (`attestation_key_mismatch`, `attestation_chain_invalid`, `custody_reference_invalid`). content: application/json: schema: type: object properties: statusCode: type: number example: 400 message: type: string example: >- attestation_nonce_invalid: registration challenge is not outstanding error: type: string example: Bad Request components: parameters: ApiVersion: name: API-Version in: header required: false schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-10-16' description: >- Pin request, response, and webhook shapes to a specific dated API version (YYYY-MM-DD). Omit to use the version pinned to your API key (set when the key is created; new keys default to the latest version). New integrations should target the latest version. schemas: RegisterAgentBody: type: object properties: cnf: type: object description: >- The agent's public key, as a P-256 JWK. Carried BESIDE the evidence, never inside it: evidence proves where a key lives and does not transport it — for an attestation the key is derived from the signed document and cross-checked against this one. example: jwk: kty: EC crv: P-256 x: … 'y': … evidence: type: object description: >- Confinement evidence (v0.3 §16.5). Every key you hold proves it is held: `proof` is a `via-reg+jwt` signed by the key over `{ cnf: { jkt }, aud, nonce, iat }` — `aud` and `nonce` from POST /agents/register-challenge. `device-self` (+ `proof`) grants pop/self; `custody` (+ `proof`) pop/custodial; `attestation-eat` and `webauthn` chained to a pinned root grant device or hardware and need no `proof`. Evidence that cannot be checked degrades — an unanchored quote to pop/self, then with `proof`. Evidence that is wrong is refused with its code; `none` is refused. example: type: device-self proof: eyJhbGciOiJFUzI1NiIsInR5cCI6InZpYS1yZWcrand0In0.… regNonce: type: string description: The single-use nonce from POST /agents/register-challenge. example: k3Jd0Q7bXm2sVQ8hZ1pYt4Rc required: - cnf - evidence - regNonce AgentRegistrationEntity: type: object properties: did: type: string description: >- The agent's DID, assigned at registration. It is not derived from the key, so a new key never changes it. example: did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35 keyId: type: string description: The genesis key id, what a mandate pins (D7). example: >- did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35#key-1 granted: description: The rung actually granted after verification. allOf: - $ref: '#/components/schemas/AgentGrantEntity' degradedFrom: type: string description: >- Present only when the evidence could not be confirmed and a LOWER rung was granted. Names what was claimed, so the loss is visible rather than silent. enum: - device - hardware example: hardware existing: type: boolean description: >- True when this key was already registered — a replay or a restart, not a new identity. example: false required: - did - keyId - granted - existing AgentGrantEntity: type: object properties: assurance: type: string description: Assurance rung the platform VERIFIED. enum: - pop - device - hardware example: hardware binding: type: string description: How the key is bound. enum: - self - custodial - attested example: attested required: - assurance - binding ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.