OpenAPI spec (raw)
Raw OpenAPI (Swagger) JSON. Served on proofenance.com; not a redirect to the API server.
{
"openapi": "3.0.0",
"paths": {
"/v1/hello": {
"get": {
"operationId": "PublicApiController_hello",
"parameters": [],
"responses": {
"200": {
"description": "OK"
}
},
"summary": "Hello (connectivity check, no auth)",
"tags": [
"Public API"
]
}
},
"/v1/reflect": {
"get": {
"operationId": "PublicApiController_reflect",
"parameters": [],
"responses": {
"200": {
"description": "Auth header and decoded payload"
},
"401": {
"description": "Missing or invalid API token"
}
},
"security": [
{
"Authorization: Bearer <your-api-key>": []
}
],
"summary": "Reflect auth (test API key)",
"tags": [
"Public API"
]
}
},
"/v1/identity/verification": {
"post": {
"operationId": "IdentityApiController_createIdentityVerification",
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateIdentityVerificationRequestDto"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateIdentityVerificationResponseDto"
}
}
}
}
},
"security": [
{
"api-key": []
}
],
"summary": "Create identity verification",
"tags": [
"Identity"
]
}
},
"/v1/identity/{personId}/status": {
"get": {
"operationId": "IdentityApiController_getIdentityStatus",
"parameters": [
{
"name": "personId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IdentityStatusResponseDto"
}
}
}
}
},
"security": [
{
"api-key": []
}
],
"summary": "Get identity status",
"tags": [
"Identity"
]
}
},
"/v1/identity/email/verify": {
"post": {
"operationId": "IdentityApiController_verifyEmail",
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyIdentityEmailRequestDto"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyIdentityEmailResponseDto"
}
}
}
},
"400": {
"description": "Invalid or expired token"
}
},
"summary": "Verify email from magic link (public)",
"tags": [
"Identity"
]
}
},
"/v1/identity/{personId}/email": {
"post": {
"operationId": "IdentityApiController_sendVerificationEmail",
"parameters": [
{
"name": "personId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SendIdentityEmailRequestDto"
}
}
}
},
"responses": {
"204": {
"description": "Email sent"
}
},
"security": [
{
"api-key": []
}
],
"summary": "Send verification email",
"tags": [
"Identity"
]
}
},
"/.well-known/jwks.json": {
"get": {
"operationId": "WellKnownController_getJwks",
"parameters": [],
"responses": {
"200": {
"description": ""
}
},
"tags": [
"WellKnown"
]
}
}
},
"info": {
"title": "Proofenance Public API",
"description": "REST API for identity verification and related operations. Base URL: api.proofenance.com/v1. Authenticate with an API token (Bearer) created in Account → API. Aligns with Open Identity / OIDC where applicable.",
"version": "1.0",
"contact": {}
},
"tags": [],
"servers": [
{
"url": "https://api.proofenance.com",
"description": "Production"
},
{
"url": "http://localhost:3000",
"description": "Local"
}
],
"components": {
"securitySchemes": {
"API token": {
"scheme": "bearer",
"bearerFormat": "JWT",
"type": "http",
"name": "Authorization",
"in": "header"
}
},
"schemas": {
"CreateIdentityVerificationRequestDto": {
"type": "object",
"properties": {
"claims": {
"type": "object",
"description": "Optional custom claims to embed in the issued identityJwt (when status is complete). Object of string keys and string values; max 5 entries; each value < 100 chars. Keys must not match reserved claims: sub, aud, iat, exp, given_name, family_name, name, birthdate, address, etc.",
"example": {
"customer_ref": "REF-123",
"tier": "premium"
}
}
}
},
"CreateIdentityVerificationResponseDto": {
"type": "object",
"properties": {
"personId": {
"type": "string",
"description": "Person entity ID; use for GET /v1/identity/:personId/status"
},
"accessCode": {
"type": "string",
"description": "Short code for in-person entry (if applicable)"
},
"gotoUrl": {
"type": "string",
"description": "URL to send the subject to complete verification (includes access code in hash)"
},
"identityJwt": {
"type": "string",
"description": "Signed identity JWT (sub=personId; no identity/email claims until verified). Validate at https://proofenance.com/.well-known/jwks.json"
}
},
"required": [
"personId",
"accessCode",
"gotoUrl",
"identityJwt"
]
},
"IdentityAddressDto": {
"type": "object",
"properties": {
"street_address": {
"type": "string",
"description": "Street address (line 1 and optionally line 2)"
},
"locality": {
"type": "string",
"description": "Locality / city"
},
"postal_code": {
"type": "string",
"description": "Postal code"
},
"country": {
"type": "string",
"description": "Country code"
}
}
},
"IdentityClaimsDto": {
"type": "object",
"properties": {
"given_name": {
"type": "string",
"description": "Given name(s)"
},
"family_name": {
"type": "string",
"description": "Family name(s)"
},
"birthdate": {
"type": "string",
"description": "Birthdate (YYYY-MM-DD)"
},
"name": {
"type": "string",
"description": "Full name"
},
"address": {
"description": "Address (OIDC format)",
"allOf": [
{
"$ref": "#/components/schemas/IdentityAddressDto"
}
]
}
}
},
"IdentityStatusResponseDto": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"pending",
"complete",
"failed",
"not_found"
]
},
"identityJwt": {
"type": "string",
"description": "Signed identity JWT (regenerated each response). Validate at https://proofenance.com/.well-known/jwks.json"
},
"gotoUrl": {
"type": "string",
"description": "URL to complete verification (when status is pending)"
},
"identity": {
"description": "Verified identity claims when status is complete.",
"allOf": [
{
"$ref": "#/components/schemas/IdentityClaimsDto"
}
]
}
},
"required": [
"status",
"identityJwt"
]
},
"VerifyIdentityEmailRequestDto": {
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "One-time token from the verification email link"
}
},
"required": [
"token"
]
},
"VerifyIdentityEmailResponseDto": {
"type": "object",
"properties": {
"companyName": {
"type": "string",
"description": "Company display name for branding"
},
"companyLogoUrl": {
"type": "string",
"description": "Company logo URL if available"
},
"redirectUrl": {
"type": "string",
"description": "Redirect URL if provided when sending the email"
}
},
"required": [
"companyName"
]
},
"SendIdentityEmailRequestDto": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address to verify"
},
"redirectUrl": {
"type": "string",
"description": "URL to redirect to after verification (optional)"
}
},
"required": [
"email"
]
}
}
}
}