# Humanos API Docs ## Docs - [Introduction](https://docs.humanos.tech/essentials/introduction.md): A cryptographic permission slip for each agent action, issued by the user, scoped to one action, and verified at runtime. - [Quick Start](https://docs.humanos.tech/essentials/quick-start.md): Get set up, then pick the guide for what you're building: collecting approvals or verifying agent actions. - [Authentication](https://docs.humanos.tech/essentials/authentication.md): Learn how to authenticate with the Humanos API using API keys and request signing - [Versioning](https://docs.humanos.tech/essentials/versioning.md): How Humanos API versions works, how to pin a version, and what happens when you don't - [Webhooks](https://docs.humanos.tech/essentials/webhooks-intro.md): Receive real-time notifications about request events and user actions - [Iframe Integration](https://docs.humanos.tech/essentials/iframe-integration.md): Embed the Humanos Link flow in an iframe, receive encrypted real-time results via postMessage, and optionally skip the OTP for high-frequency approvals with trusted sessions - [Collecting Approvals](https://docs.humanos.tech/essentials/guides/collecting-approvals.md): Request signed approvals, such as consents, forms, documents, or JSON, from your users, delivered by link or embedded iframe, with optional identity verification. - [Agent Actions](https://docs.humanos.tech/essentials/guides/verifying-agent-actions.md): Let an AI agent act under a scoped, user-approved policy: publish an action, request a mandate, issue a verifiable presentation, and verify it at execution time. - [List Requests](https://docs.humanos.tech/api-reference/latest/requests/list-requests.md): Retrieve a paginated list of your credential requests Each request includes information about the request, credentials, subjects (users) and chosen security level Optional query parameters filter the results: search (matches request or credential name), dateFrom/dateTo (creation-date range), sub… - [Create Request](https://docs.humanos.tech/api-reference/latest/requests/create-request.md): Create a new request for one or more subjects (users). This endpoint will: - Create credentials from resources (via group IDs, resource IDs) or inline JSON data - Associate those credentials with subjects - Generate and send OTPs via email or SMS - [Get Detail](https://docs.humanos.tech/api-reference/latest/requests/get-detail.md): Retrieve detailed information about a specific credential request Just like the list requests endpoint, this endpoint includes information about the request, credentials, subjects (users) and chosen security level However, this endpoint includes the full W3C Verifiable Credential data for each c… - [Cancel Request](https://docs.humanos.tech/api-reference/latest/requests/cancel-request.md): This action will cancel a credential request. Once a request is canceled, it cannot be undone and will prevent the request from being completed by any subjects. Any draft credentials are marked canceled and any already-active credentials in the request are revoked. - [Resend OTP](https://docs.humanos.tech/api-reference/latest/requests/resend-otp.md): Resend a One-Time Password (OTP) to a subject for credential approval, via email or SMS. Provide exactly one query parameter to identify the subject: contact, id, or internalId. The endpoint validates: - The request is not canceled - Maximum attempts have not been reached, only successful… - [Get Evidence](https://docs.humanos.tech/api-reference/latest/credentials/get-evidence.md): Fetch the raw content of an evidence file attached to a credential. `evidenceId` must be an evidence URN (`urn:via:evidence:`); a malformed URN returns 400. The response body is the evidence content (e.g. base64-encoded file, JSON). - [Get Credential](https://docs.humanos.tech/api-reference/latest/credentials/get-credential.md): Retrieve a credential by its identifier, including the full W3C Verifiable Credential, and the latest status of all grantor decisions. The `credentialId` must be a credential URN (`urn:via:credential:`); a malformed URN returns 400. - [Issue VP](https://docs.humanos.tech/api-reference/latest/credentials/issue-vp.md): Build and sign a W3C Verifiable Presentation for a stored credential. The API key must belong to the credential owner (its DID must be on the mandate authorizedDIDs). Optionally pass `targetVerifier` in the request body — the verifier domain, e.g. "organization.com" — to bind the VP to that audience… - [Verify VP](https://docs.humanos.tech/api-reference/latest/credentials/verify-vp.md): Evaluate a VP against runtime context. On allow, returns 201 with the signed receipt. On deny, returns 403 with the reason, evaluations, and receipt in the error body. If the mandate has no constraint schema, only signatures, verifier access, and validity are checked. - [Revoke Credential](https://docs.humanos.tech/api-reference/latest/credentials/revoke-credential.md): Permanently revoke an active credential. Flips status to REVOKED, records revokedAt and revocationReason, appends a REVOKE proof to the credential, and emits a MANDATE_REVOKED activity event. Optionally include a `reason` (max 200 chars) in the request body to record why the credential was revoked;… - [Get Actions](https://docs.humanos.tech/api-reference/latest/actions/get-actions.md): Retrieve a paginated list of actions for the authenticated organization. Only published versions are ever exposed here; drafts are hidden from public clients. Each action includes up to its 10 most recent published versions (newest first); use GET /actions/version/{id} to page through the full versi… - [Get Versions](https://docs.humanos.tech/api-reference/latest/actions/get-versions.md): Retrieve a paginated list of an action's published versions, newest first, for the action identified by the `id` path parameter. Each version includes its full JSON `content`, its `digestSRI`, and publication metadata; drafts are hidden from public clients. Supports pagination via `pageIndex` and `p… - [Get User](https://docs.humanos.tech/api-reference/latest/user/get-user.md): Retrieves detailed information about a user. Search by exactly one parameter: contact, id, or internalId. Only one must be provided. - [Create User](https://docs.humanos.tech/api-reference/latest/user/create-user.md): This endpoint allows organizations to import their existing users' information into Humanos, for better management and control. - Between 1 and 100 users can be created per request. - A user is identified by a Humanos-verified contact (email or phone); if it does not exist, it will be created… - [Resolve DID](https://docs.humanos.tech/api-reference/latest/did/resolve-did.md): Resolve a DID to its W3C DID 1.1 Document. Only DIDs with ACTIVE status resolve; an unknown or non-active DID returns 404. The document lists every registered key under `verificationMethod`, while `authentication` and `assertionMethod` reference only non-revoked keys. - [List Approvals](https://docs.humanos.tech/api-reference/latest/approval/list-approvals.md): Retrieve a paginated list of your approvals. Approvals can be of type `CONSENT`, `FORM`, `DOCUMENT`, `JSON`, or `POLICY`. Filter with the optional query parameters: `search` (case-insensitive match on the approval name), `active` (active or inactive approvals only), `types` (one or more resource t… - [List Workflows](https://docs.humanos.tech/api-reference/latest/approval/list-workflows.md): Retrieve a paginated list of your workflows, including their approvals. Workflows let you pack approvals together and request them easily. Filter with the optional query parameters: `search` (matches the workflow name or the name of a contained approval), `active` (active or inactive workflows o… - [List Activity Events](https://docs.humanos.tech/api-reference/latest/activity/list-activity-events.md): Retrieve a paginated list of activity events for your organization. Events are returned in descending chronological order (most recent first). Filter by event `type`, `entityType`, `entityId`, `actorDid`, `subjectDid`, or a `dateFrom`/`dateTo` range. Paginate with `pageIndex` (zero-based, defa… - [Credential Event](https://docs.humanos.tech/api-reference/latest/webhooks/credential-event.md): Fired when a credential request is accepted or rejected by the subject. - [Identity Event](https://docs.humanos.tech/api-reference/latest/webhooks/identity-event.md): Fired when an identity verification (KYC) decision is reached. - [OTP Failed Event](https://docs.humanos.tech/api-reference/latest/webhooks/otp-failed-event.md): Fired when an OTP **SMS** could not be delivered: every eligible SMS provider was tried (synchronously or via carrier delivery reports) and none succeeded. Email OTP failures do not emit this event. Carrier delivery reports are asynchronous and occasionally corrected to "delivered" afterwards, so tr… - [Test Event](https://docs.humanos.tech/api-reference/latest/webhooks/test-event.md): Fired when a webhook test is triggered from the dashboard. ## OpenAPI Specs - [2026-07-06](https://docs.humanos.tech/versions/2026-07-06.yaml) - [2026-06-18](https://docs.humanos.tech/versions/2026-06-18.yaml) - [2026-05-17](https://docs.humanos.tech/versions/2026-05-17.yaml) - [2026-03-20](https://docs.humanos.tech/versions/2026-03-20.yaml) - [openapi](https://docs.humanos.tech/openapi.yaml) - [humanos-api](https://docs.humanos.tech/humanos-api.yml)