Issue VP

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 via proof.domain and a challenge nonce; omit it for an unbound VP.

POST /credential/vp/{vcId}

Issue VP

cURL

curl --request POST \
  --url https://api.example.com/credential/vp/{vcId} \
  --header 'Content-Type: application/json' \
  --data '
{
  "targetVerifier": "organization.com"
}
'

import requests

url = "https://api.example.com/credential/vp/{vcId}"

payload = { "targetVerifier": "organization.com" }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({targetVerifier: 'organization.com'})
};

fetch('https://api.example.com/credential/vp/{vcId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/credential/vp/{vcId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'targetVerifier' => 'organization.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/credential/vp/{vcId}"

	payload := strings.NewReader("{\n  \"targetVerifier\": \"organization.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/credential/vp/{vcId}")
  .header("Content-Type", "application/json")
  .body("{\n  \"targetVerifier\": \"organization.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/credential/vp/{vcId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"targetVerifier\": \"organization.com\"\n}"

response = http.request(request)
puts response.read_body

201

{
  "presentation": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://via.humanos.dev/ns/v1"
    ],
    "type": [
      "VerifiablePresentation"
    ],
    "holder": "did:web:humanos.tech:org:550e8400-e29b-41d4-a716-446655440000",
    "verifiableCredential": {
      "@context": [
        "https://www.w3.org/ns/credentials/v2",
        "https://via.humanos.dev/ns/v1"
      ],
      "id": "urn:via:credential:550e8400-e29b-41d4-a716-446655440000",
      "type": [
        "VerifiableCredential",
        "VIAMandate"
      ],
      "issuer": "did:web:humanos.tech",
      "validFrom": "2025-01-01T00:00:00Z",
      "validUntil": null,
      "credentialSubject": {
        "id": "did:web:humanos.tech:org:550e8400-e29b-41d4-a716-446655440000",
        "mandate": {
          "grantor": "did:web:humanos.tech:user:7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "scope": "humanos.credential.request",
          "context": {
            "authorizedDIDs": [
              "did:web:humanos.tech:org:550e8400-e29b-41d4-a716-446655440000",
              "did:web:humanos.tech:user:7c9e6679-7425-40de-944b-e07fc1f90ae7"
            ]
          }
        }
      },
      "evidences": [
        {
          "id": "urn:via:evidence:9b2e4f1a-3c7d-4e8a-bf12-2a6c5d8e0f34",
          "digestSRI": "sha256-abc123",
          "location": "https://api.humanos.dev/credential/evidence/urn:via:evidence:9b2e4f1a-3c7d-4e8a-bf12-2a6c5d8e0f34"
        }
      ]
    },
    "proof": {
      "type": "DataIntegrityProof",
      "cryptosuite": "eddsa-jcs-2022",
      "created": "2026-05-02T10:15:30.000Z",
      "verificationMethod": "did:web:humanos.tech#key-1",
      "proofPurpose": "authentication",
      "proofValue": "z2pcVdSdoMTrkYP9rVdz..."
    }
  },
  "presentationEncoded": "eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiXX0=",
  "receipt": {
    "id": "urn:via:receipt:c4bb2c9d-9b37-448b-8f1a-4ac5793945be",
    "timestamp": "2026-05-02T10:15:30.000Z"
  }
}

{
  "statusCode": 400,
  "message": "Credential is not ACTIVE / expired / not yet valid",
  "error": "Bad Request"
}

{
  "statusCode": 403,
  "message": "Credential is not accessible by this API key",
  "error": "Forbidden"
}

{
  "statusCode": 404,
  "message": "Credential not found",
  "error": "Not Found"
}

Headers

API-Version · string

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.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-07-06"

Path Parameters

vcId · string · required

URN of the credential to present.

Example:

"urn:via:credential:550e8400-e29b-41d4-a716-446655440000"

Body

application/json

targetVerifier · string

Domain or subdomain of the intended verifier (e.g. "organization.com"). When provided, the VP is bound to this audience via proof.domain and a challenge nonce.

Example:

"organization.com"

Response

201

application/json

Signed Verifiable Presentation and VP_CREATED receipt.

presentation · object · required

Signed W3C Verifiable Presentation (@context, type, holder, verifiableCredential, proof), exactly as returned by POST /credential/vp/:vcId — do not re-serialize or modify it. Provide this or presentationEncoded (at least one is required; presentationEncoded overrides and is recommended, since a base64 string avoids JSON formatting changes that can break the signature).

Example:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://via.humanos.dev/ns/v1"
  ],
  "type": ["VerifiablePresentation"],
  "holder": "did:web:humanos.tech:org:550e8400-e29b-41d4-a716-446655440000",
  "verifiableCredential": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://via.humanos.dev/ns/v1"
    ],
    "id": "urn:via:credential:550e8400-e29b-41d4-a716-446655440000",
    "type": ["VerifiableCredential", "VIAMandate"],
    "issuer": "did:web:humanos.tech",
    "validFrom": "2025-01-01T00:00:00Z",
    "validUntil": null,
    "credentialSubject": {
      "id": "did:web:humanos.tech:org:550e8400-e29b-41d4-a716-446655440000",
      "mandate": {
        "grantor": "did:web:humanos.tech:user:7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "scope": "humanos.credential.request",
        "context": {
          "authorizedDIDs": [
            "did:web:humanos.tech:org:550e8400-e29b-41d4-a716-446655440000",
            "did:web:humanos.tech:user:7c9e6679-7425-40de-944b-e07fc1f90ae7"
          ]
        }
      }
    },
    "evidences": [
      {
        "id": "urn:via:evidence:9b2e4f1a-3c7d-4e8a-bf12-2a6c5d8e0f34",
        "digestSRI": "sha256-abc123",
        "location": "https://api.humanos.dev/credential/evidence/urn:via:evidence:9b2e4f1a-3c7d-4e8a-bf12-2a6c5d8e0f34"
      }
    ]
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2026-05-02T10:15:30.000Z",
    "verificationMethod": "did:web:humanos.tech#key-1",
    "proofPurpose": "authentication",
    "proofValue": "z2pcVdSdoMTrkYP9rVdz..."
  }
}

presentationEncoded · string · required

Base64-encoded JSON of the signed Verifiable Presentation above. Pass it back to POST /credential/verify as presentationEncoded (recommended) to avoid signature failures caused by JSON re-serialization in some HTTP clients.

Example:

"eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiXX0="

receipt · object · required

VP_CREATED receipt issued for this presentation

Show child attributes