Humanos - Programmable Human Authorization for Agent Actions

Humanos - Programmable Human Authorization for Agent Actions

AI agents can execute actions. Humanos lets them prove human authorization before they do.

Require a mandate signature before high-risk execution.

What It Does

Humanos provides the authorization proof. Your runtime decides whether to execute.

When To Use It

Use Humanos when your agent can:

If the action affects money, data, identity, ownership, or legal position, require a mandate signature.

How It Works

1. Agent prepares a structured action 2. Agent calls requestMandate(action, constraints) 3. Human approves via SMS, email, wallet, API, or any programmable channel 4. Humanos returns a signed mandate signature 5. Agent verifies with verifyMandate(signature) 6. Agent decides whether to execute

No valid mandate signature -> execution should not proceed.

Core API

requestMandate(action, constraints) -> mandate_signature verifyMandate(mandate_signature) -> true / false revokeMandate(mandate_signature)

Simple. Programmable. Deterministic.

VIA Humanos - Operational Instructions for Agents

Use this skill whenever the agent is about to do something that requires a human to say "yes" first. It sends a secure approval request to the right person - they receive a link, review the details, and approve or reject. The result comes back as a W3C Verifiable Credential with cryptographic proof that the action was authorized.

The agent should NEVER proceed with a sensitive action (payment, signing, data access, transfer) without first using this skill to get authorization.

When to use this skill

Use this skill when the user says things like:

Also use this skill when the agent is about to:

Trigger keywords: approval, authorize, mandate, sign, consent, credential, KYC, identity verification, human approval, compliance, permission, delegation.

Prerequisites

1. A VIA Protocol account with an API key from app.humanos.id 2. Environment variables set: - VIA_API_KEY — Bearer token for API authentication - VIA_SIGNATURE_SECRET — HMAC secret for request signing - Optional: VIA_API_URL — Override API base URL (default: https://api.humanos.id)

Windows note: this skill is currently supported on macOS/Linux shells. On Windows, use WSL or Git Bash with bash, curl, jq, and openssl installed.

Authentication

All API requests require:

Authorization: Bearer $VIA_API_KEY
X-Timestamp: 
X-Signature: 

Use the signing script: scripts/sign-request.sh

Official API documentation: https://humanos.mintlify.app/essentials/introduction

Operation Index (Fast Lookup)

Use this as the primary lookup table before reading detailed sections.

| Goal | Script | Method | Endpoint | Required Args | | --- | --- | --- | --- | --- | | Create approval request | scripts/create-request.sh | POST | /v1/request | --contact, --type, --name | | Check request status | scripts/get-request.sh | GET | /v1/request/:id | --id | | Find requests | scripts/find-requests.sh | GET | /v1/request?contact|did|internalId | one of --contact, --did, --internal-id | | Get credential proof | scripts/get-credential.sh | GET | /v1/credential/:id | --id | | Get mandate | scripts/get-mandate.sh | GET | /v1/via/mandates/:id | --id | | Get mandate VC | scripts/get-mandate-vc.sh | GET | /v1/via/mandates/:id/vc | --id | | Resolve DID | scripts/resolve-did.sh | GET | /v1/via/dids/:did | --did | | Look up user | scripts/get-user.sh | GET | /v1/user?contact|did|internalId | one of --contact, --did, --internal-id | | Cancel request | scripts/cancel-request.sh | DELETE | /v1/request/:id | --id | | Resend OTP | scripts/resend-otp.sh | PATCH | /v1/request/resend/:id | --id (and optional --contact) |

Create Request Rules (Critical)

Follow these rules to avoid generic 400 Failed to generate credentials request responses.

1. Use --type as: document, consent, or json (lowercase input; script converts internally). 2. form is not supported as inline credential in this script. Use resource IDs for forms. 3. --data should be JSON array of fields. A single object is also accepted and auto-wrapped. 4. Every field should follow: - label (string) - type (string, number, boolean, date, url, pdf, object, array) - value (matches type) - hidden (boolean; defaults to false) 5. Type-specific mandatory fields: - consent: must include {"label":"text","type":"string","value":"...","hidden":false} - document: must include {"label":"pdf","type":"pdf","value":"","hidden":false}

Valid examples (copy/paste)

Consent (recommended for simple approvals):

scripts/create-request.sh \
  --contact "+351919307983" \
  --type "consent" \
  --name "Football approval" \
  --data '[{"label":"text","type":"string","value":"I approve football tomorrow.","hidden":false}]'

JSON mandate:

scripts/create-request.sh \
  --contact "user@example.com" \
  --type "json" \
  --name "Hotel Booking Authorization" \
  --data '[
    {"label":"amount","type":"number","value":450,"hidden":false},
    {"label":"currency","type":"string","value":"EUR","hidden":false}
  ]'

Document signature:

scripts/create-request.sh \
  --contact "user@example.com" \
  --type "document" \
  --name "NDA Signature" \
  --data '[{"label":"pdf","type":"pdf","value":"","hidden":false}]'

Signing Algorithm (Exact Bytes, Critical)

All 401 Invalid signature incidents should be debugged against this section.

1. Build the request body once. 2. Keep the body as a compact JSON string. 3. Generate timestamp in unix milliseconds (13 digits). 4. Compute payload as: - timestamp + "." + body when body is not empty - timestamp when body is empty 5. Compute signature = HMAC_SHA256_HEX(payload, VIA_SIGNATURE_SECRET). 6. Send exactly the same body bytes in the HTTP request.

Deterministic checklist

Common failure modes

Core Operations

1. Create a Credential Request (Get Human Approval)

When the agent needs human authorization for an action:

scripts/create-request.sh \
  --contact "user@example.com" \
  --type "json" \
  --name "Hotel Booking Authorization" \
  --security "CONTACT" \
  --data '[{"label":"amount","type":"number","value":450,"hidden":false}]'

Parameters:

What happens: 1. The API creates the request and sends an OTP code to the contact 2. The person opens the link, enters the code, and sees the approval 3. They approve or reject with optional digital signature 4. You receive a webhook or poll for the result

Response includes: requestId — save this to check status later.

2. Check Request Status

scripts/get-request.sh --id "request-id-here"

Returns the full request with all credentials and their statuses (PENDING, APPROVED, REJECTED).

3. Find Requests by User

scripts/find-requests.sh --contact "user@example.com"
or
scripts/find-requests.sh --did "did:key:z6Mk..."
or
scripts/find-requests.sh --internal-id "order-123"

4. Get a Credential with Proofs

scripts/get-credential.sh --id "credential-id-here"

Returns the W3C Verifiable Credential with cryptographic proofs that the human authorized the action.

5. Get a Mandate

scripts/get-mandate.sh --id "mdt_uuid-here"

Returns mandate details including scope, validity period, and constraints.

6. Get Mandate as Verifiable Credential

scripts/get-mandate-vc.sh --id "mdt_uuid-here"

Returns the mandate in W3C Verifiable Credential format for use in Verifiable Presentations.

7. Resolve a DID

scripts/resolve-did.sh --did "did:key:z6Mk..."

Returns the DID Document with verification methods. Use this to verify signatures on credentials.

8. Look Up a User

scripts/get-user.sh --contact "user@example.com"

Returns user details, identity information, and associated DIDs.

9. Cancel a Request

scripts/cancel-request.sh --id "request-id-here"

Cancels a pending request. This is irreversible.

10. Resend OTP

scripts/resend-otp.sh --id "request-id-here" --contact "user@example.com"

Resends the verification code to the user if they didn't receive it.

Decision Flow

When you need human approval, follow this flow:

1. Create request → scripts/create-request.sh 2. Wait for approval → Poll with scripts/get-request.sh or wait for webhook 3. Check result: - APPROVED → Proceed with the action. The credential contains cryptographic proof. - REJECTED → Do NOT proceed. Inform the user the action was denied. - PENDING → Still waiting. Ask the user if they want to resend the OTP.

Security Levels

| Level | Description | Use When | | --- | --- | --- | | CONTACT | OTP verification only | Low-risk actions (view data, basic approvals) | | ORGANIZATION_KYC | Organization-level identity check | Medium-risk (sign documents, access records) | | HUMANOS_KYC | Full KYC with identity verification | High-risk (payments, legal signatures) | | HUMANOS_REVALIDATION | Re-verification of previously verified identity | Periodic re-checks |

Credential Types

| Type | Description | User Experience | | --- | --- | --- | | document | PDF document for review and signature | User sees PDF, can draw signature | | form | Dynamic form with fields | User fills form fields step by step | | json | Structured data for review | User sees data and approves/rejects | | consent | Consent text or URL | User reads and agrees to terms |

Rate Limits

Error Handling

401 Invalid Signature Playbook

Follow this exact sequence before escalating:

1. Confirm endpoint is https://api.humanos.id. 2. Confirm timestamp is 13-digit numeric milliseconds. 3. Confirm signing payload is exactly: - timestamp + "." + body (non-empty body), or - timestamp (empty body). 4. Confirm signed body bytes are the same bytes sent to curl. 5. Confirm VIA_SIGNATURE_SECRET and VIA_API_KEY come from the same environment. 6. Retry with a minimal JSON payload (single credential, no optional fields). 7. If GET works and POST still fails, capture request metadata for backend support: - endpoint path - timestamp - body length - sha256(body) - signature format (hex/base64)

Escalation note for support: "GET succeeds with same key/secret, POST returns 401 Invalid signature using payload=timestamp.body."

Output Format

Always present results to the user in this format:

For request creation: > Request created successfully. An approval link has been sent to [contact]. > Request ID: [id] > Status: PENDING

For status checks: > Request [id] — Status: [APPROVED/REJECTED/PENDING] > Credential: [name] — [status] > Approved by: [contact] on [date]

For errors: > Failed to [action]: [error message] > Suggestion: [what to do next]

External Endpoints

| Endpoint | Data Sent | Purpose | | --- | --- | --- | | $VIA_API_URL/v1/request | Contacts, credential data | Create approval requests | | $VIA_API_URL/v1/request/:id | Request ID | Check approval status | | $VIA_API_URL/v1/credential/:id | Credential ID | Retrieve signed credentials | | $VIA_API_URL/v1/via/mandates/:id | Mandate ID | Get mandate details | | $VIA_API_URL/v1/via/mandates?scope=&toolName= | Scope, tool name | Query mandates for policy checks | | $VIA_API_URL/v1/via/dids/:did | DID identifier | Resolve DID documents | | $VIA_API_URL/v1/user | Contact/DID/internal ID | Look up users |

Default base URL is https://api.humanos.id when VIA_API_URL is not set.

Security and Privacy

1. A VIA Protocol account with an API key from app.humanos.id 2. Environment variables set: - VIA_API_KEY — Bearer token for API authentication - VIA_SIGNATURE_SECRET — HMAC secret for request signing - Optional: VIA_API_URL — Override API base URL (default: https://api.humanos.id)

Windows note: this skill is currently supported on macOS/Linux shells. On Windows, use WSL or Git Bash with bash, curl, jq, and openssl installed.