{ "openapi": "3.2.1", "info": { "title": "LeanIdent Identity & Evidence API", "version": "0.1.0", "description": "Development contract for the independent LeanIdent service. Veriff is the first evidence source; owned services will replace provider functions incrementally. Production activation and LeanShare cutover remain separate. Browser sessions are obtained only through the configured shared OIDC authority." }, "servers": [ { "url": "https://leanident.de", "description": "Intended canonical domain; production activation not asserted" } ], "paths": { "/health": { "get": { "operationId": "getHealth", "summary": "Process liveness", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "service": { "const": "leanident" }, "status": { "const": "ok" } }, "required": [ "service", "status" ] } } } }, "400": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Actual configured capabilities", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capabilities" } } } }, "400": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/jwks.json": { "get": { "operationId": "getSigningKeys", "summary": "Public evidence verification keys", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "keys": { "type": "array", "items": { "type": "object" } } }, "required": [ "keys" ] } } } }, "400": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/me/evidence": { "get": { "operationId": "listMyEvidence", "summary": "Read evidence for the authenticated account", "security": [ { "accessToken": [] } ], "x-required-scope": "leanident:read", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "evidence": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/Evidence" } } }, "required": [ "evidence" ] } } } }, "400": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/verifications": { "post": { "operationId": "startVerification", "summary": "Create or reconcile one document/selfie check", "security": [ { "accessToken": [] } ], "x-required-scope": "leanident:verify", "responses": { "202": { "description": "Verification accepted or existing transaction reconciled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "400": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Explicit processing consent and a provisioned bounded tenant budget are required. An uncertain external request is not retried. Same idempotency key returns the original transaction.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationRequest" } } } } } }, "/v1/verifications/{id}": { "get": { "operationId": "getVerification", "summary": "Read and reconcile an owned verification", "security": [ { "accessToken": [] } ], "x-required-scope": "leanident:verify", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "400": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/me/evidence/{id}/revoke": { "post": { "operationId": "revokeMyEvidence", "summary": "Revoke owned evidence and dependent presentations", "security": [ { "accessToken": [] } ], "x-required-scope": "leanident:revoke", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "revoked": { "const": true } }, "required": [ "revoked" ] } } } }, "400": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } } } }, "/v1/presentations": { "post": { "operationId": "issuePresentation", "summary": "Issue a purpose-bound minimal signed evidence presentation", "security": [ { "accessToken": [] } ], "x-required-scope": "leanident:present", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Presentation" } } } }, "400": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Only approved delegated end-user clients may assert specific consent. Server registry restricts tenant, client, audience, purpose and attributes. Nonce is one-use per account/client; presentation lifetime at most 120 seconds. Does not itself grant access to documents or prove legal service.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresentationRequest" } } } } } }, "/v1/presentations/{id}/status": { "post": { "operationId": "getPresentationStatus", "summary": "Check current presentation and evidence validity", "security": [ { "accessToken": [] } ], "x-required-scope": "leanident:introspect", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "active": { "type": "boolean" } }, "required": [ "active" ] } } } }, "400": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } }, "description": "Only the issuing registered tenant/client may inspect a presentation. Must be used in addition to signature and transaction binding checks." } }, "/v1/providers/veriff/webhook": { "post": { "operationId": "receiveVeriffDecision", "summary": "Authenticated provider decision callback", "security": [ { "veriffClient": [], "veriffSignature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Veriff decision payload; exact raw bytes authenticated before decoding, then checked against persisted session and opaque account binding." } } } }, "responses": { "204": { "description": "Authenticated callback processed idempotently, or unknown session safely acknowledged" }, "400": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Evidence": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "attribute": { "type": "string", "enum": [ "PERSON_VERIFIED", "LEGAL_NAME_VERIFIED", "AGE_OVER_18", "POSTAL_ADDRESS_VERIFIED", "EMAIL_CONTROLLED" ] }, "source": { "type": "string", "minLength": 1, "maxLength": 200 }, "method": { "type": "string", "minLength": 1, "maxLength": 200 }, "verifiedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "CURRENT", "EXPIRED", "REVOKED" ] } }, "required": [ "id", "attribute", "source", "method", "verifiedAt", "expiresAt", "revokedAt", "status" ] }, "Verification": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "CREATING", "PENDING", "APPROVED", "DECLINED", "EXPIRED", "CANCELLED", "REVIEW", "RESUBMISSION_REQUESTED" ] }, "authorizationUrl": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "id", "state", "authorizationUrl" ] }, "VerificationRequest": { "type": "object", "additionalProperties": false, "properties": { "consentVersion": { "type": "string", "const": "leanident-veriff-document-selfie-v1" } }, "required": [ "consentVersion" ] }, "PresentationRequest": { "type": "object", "additionalProperties": false, "properties": { "audience": { "type": "string", "minLength": 1, "maxLength": 200 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 200 }, "attributes": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "type": "string", "enum": [ "PERSON_VERIFIED", "LEGAL_NAME_VERIFIED", "AGE_OVER_18", "POSTAL_ADDRESS_VERIFIED", "EMAIL_CONTROLLED" ] } }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43,128}$" }, "consent": { "type": "boolean", "const": true } }, "required": [ "audience", "purpose", "attributes", "nonce", "consent" ] }, "Presentation": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "token": { "type": "string", "description": "ES256 JWT, typ leanident-evidence+jwt. Verify issuer, audience, nonce, purpose, exp and active status. Pairwise subject; no raw person attributes." }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "token", "expiresAt" ] }, "Capabilities": { "type": "object", "additionalProperties": false, "properties": { "authentication": { "type": "boolean" }, "verification": { "type": "boolean" }, "presentations": { "type": "boolean" }, "consentVersion": { "type": "string" } }, "required": [ "authentication", "verification", "presentations", "consentVersion" ] } }, "securitySchemes": { "accessToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Signed short-lived at+jwt from pinned shared issuer and JWKS. Claims sub, tenant_id, client_id, scope, iat and exp. Maximum age and lifetime 5 minutes; registered tenant/client required. Browser BFF stores the token encrypted and uses an HttpOnly cookie with same-origin mutation checks." }, "veriffClient": { "type": "apiKey", "in": "header", "name": "X-AUTH-CLIENT" }, "veriffSignature": { "type": "apiKey", "in": "header", "name": "X-HMAC-SIGNATURE" } } } }