Docs API Reference SDK Reference Patterns Community

Create Passport

POST

Creates a new cryptographic identity (Passport) with a decentralized identifier (DID).

Endpoint

bash

POST /v1/passports

Request Body

Parameter	Type	Required	Description
type	string	Required	Type of Passport. One of: `individual`, `organization`, `agent`
name	string	Required	Display name for the Passport holder
metadata	object	Optional	Additional metadata (email, organization, etc.)
capabilities	string[]	Optional	Array of initial capability IDs to grant

Example Request

json

{
  "type": "individual",
  "name": "Alice Smith",
  "metadata": {
    "email": "alice@example.com",
    "organization": "optional"
  },
  "capabilities": ["optional-initial-capabilities"]
}

Response

Returns a 201 Created status with the newly created Passport object.

Field	Type	Description
data.passportId	string	Unique identifier for this Passport (use for API calls)
data.did	string	Decentralized identifier (DID) - globally unique, cryptographically verifiable
data.type	string	Type of Passport (individual, organization, or agent)
data.name	string	Display name
data.publicKey	string	Public key for cryptographic verification
data.createdAt	string	ISO 8601 timestamp of creation
meta.timestamp	string	Server processing timestamp
meta.requestId	string	Unique request ID for debugging and support

Example Response

json

{
  "data": {
    "passportId": "passport_abc123",
    "did": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
    "type": "individual",
    "name": "Alice Smith",
    "publicKey": "0x...",
    "createdAt": "2024-01-10T14:30:00Z"
  },
  "meta": {
    "timestamp": "2024-01-10T14:30:00Z",
    "requestId": "req_create_passport_xyz"
  }
}

Example Request

SDK:

Error Responses

Status Code	Error Code	Description
400	invalid_request	Missing required fields or invalid parameter values
401	unauthorized	Missing or invalid API key
429	rate_limit_exceeded	Too many requests - see rate limit headers
500	internal_error	Server error - contact support with requestId

What Happens

• HumanOS generates a cryptographic DID
• A public/private key pair is created
• The Passport is registered on the distributed ledger
• Initial provenance log is created
• You receive the Passport ID and DID for future operations