hConnect is a unified API for global eID identity verification. It exposes two surfaces: an OIDC OpenID Provider (authorization, token, userinfo, jwks, discovery) for browser sign-in flows, and a REST API for provider discovery and the verification lifecycle (create verification, poll status, read normalized user claims and provenance), plus a Workspace API for managing Apps, providers, workflows, webhooks, and production tests.
{
"openapi": "3.0.0",
"info": {
"title": "hConnect API",
"description": "The hConnect API provides a unified interface for electronic identity verification across multiple eID providers globally.",
"version": "1.0.0",
"contact": {
"name": "hConnect Support",
"url": "https://www.hopae.com",
"email": "dev@hopae.com"
}
},
"servers": [
{
"url": "https://sandbox.api.hopae.com/connect",
"description": "Sandbox Server"
}
],
"tags": [
{
"name": "Console - API Keys",
"description": "Workspace API key management (Console)"
},
{
"name": "Providers",
"description": "eID provider discovery"
},
{
"name": "Token",
"description": "OAuth 2.0 token exchange"
},
{
"name": "Verifications",
"description": "Identity verification sessions"
},
{
"name": "Workspace API - Activation",
"description": "Provider activation per app"
},
{
"name": "Workspace API - Apps",
"description": "App management"
},
{
"name": "Workspace API - Production Tests",
"description": "Production test challenges"
},
{
"name": "Workspace API - Workflows",
"description": "Workflow configuration per app"
},
{
"name": "Workspace API - Workspace",
"description": "Workspace information"
}
],
"paths": {
"/v1/providers": {
"get": {
"summary": "Get Providers",
"description": "Retrieves a list of available eID providers.",
"operationId": "getProviders",
"tags": [
"Providers"
],
"parameters": [
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"activated",
"deactivated",
"action_required"
]
},
"description": "The status of the provider."
}
],
"responses": {
"200": {
"description": "Providers retrieved successfully.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier for the eID provider"
},
"logoUrl": {
"type": "string",
"description": "The URL of the eID provider's logo"
},
"name": {
"type": "string",
"description": "The display name of the eID provider"
},
"description": {
"type": "string",
"description": "A description of the eID provider"
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "The countries supported by the eID provider"
},
"status": {
"type": "string",
"enum": [
"activated",
"deactivated",
"action_required"
],
"description": "The current status of the provider"
}
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid parameters or eID not enabled."
},
"401": {
"description": "Unauthorized - Invalid client credentials."
}
}
}
},
"/v1/verifications": {
"post": {
"summary": "Create Verification",
"description": "Initiates a new identity verification session with the specified eID provider.",
"operationId": "createVerification",
"tags": [
"Verifications"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateVerificationRequest"
}
}
}
},
"responses": {
"201": {
"description": "Verification session created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateVerificationResponse"
}
}
}
},
"400": {
"description": "Bad Request - Invalid parameters or eID not enabled."
},
"401": {
"description": "Unauthorized - Invalid client credentials."
}
}
}
},
"/v1/verifications/{verificationId}": {
"get": {
"summary": "Get Verification Status",
"description": "Retrieves the current status and result of a verification session.",
"operationId": "getVerification",
"tags": [
"Verifications"
],
"parameters": [
{
"name": "verificationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The unique identifier for the verification session."
}
],
"responses": {
"200": {
"description": "Verification status retrieved successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetVerificationResponse"
}
}
}
},
"404": {
"description": "Verification not found."
}
}
},
"delete": {
"summary": "Cancel Verification",
"description": "Cancels and deletes an ongoing verification session.",
"operationId": "deleteVerification",
"tags": [
"Verifications"
],
"parameters": [
{
"name": "verificationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The unique identifier for the verification session."
}
],
"responses": {
"204": {
"description": "Verification cancelled successfully."
},
"400": {
"description": "Bad Request - Verification is already in a terminal state."
},
"404": {
"description": "Verification not found."
}
}
}
},
"/token": {
"post": {
"summary": "Exchange Code for Token",
"description": "Exchanges an authorization code for an ID token, following the OAuth 2.0 standard.",
"operationId": "exchangeCodeForToken",
"tags": [
"Token"
],
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenRequest"
}
}
}
},
"responses": {
"200": {
"description": "Token exchange successful.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id_token": {
"type": "string",
"description": "A JWT containing the user's verified claims."
}
}
}
}
}
},
"400": {
"description": "Bad Request - Invalid grant_type or missing parameters."
},
"401": {
"description": "Unauthorized - Invalid code or client credentials."
}
}
}
},
"/v1/workspace": {
"get": {
"operationId": "WorkspaceController_getWorkspace",
"summary": "Get workspace information",
"description": "Retrieve workspace details including app count",
"parameters": [],
"responses": {
"200": {
"description": "Workspace information",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceResponseDto"
}
}
}
},
"401": {
"description": "Invalid API key"
}
},
"tags": [
"Workspace API - Workspace"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps": {
"post": {
"operationId": "WorkspaceAppsController_createApp",
"summary": "Create a new app",
"description": "Create a new application in the workspace",
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAppDto"
}
}
}
},
"responses": {
"201": {
"description": "App created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceAppDto"
}
}
},
"headers": {
"Location": {
"description": "URL of the newly created app (e.g., /v1/apps/FK5b0KSM).",
"schema": {
"type": "string",
"format": "uri-reference"
}
}
}
},
"401": {
"description": "Invalid API key"
}
},
"tags": [
"Workspace API - Apps"
],
"security": [
{
"workspace-api-key": []
}
]
},
"get": {
"operationId": "WorkspaceAppsController_listApps",
"summary": "List all apps",
"description": "Get all applications in the workspace with pagination",
"parameters": [
{
"name": "limit",
"required": true,
"in": "query",
"schema": {
"type": "number"
}
},
{
"name": "offset",
"required": true,
"in": "query",
"schema": {
"type": "number"
}
}
],
"responses": {
"200": {
"description": "Apps retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedAppsResponseDto"
}
}
}
},
"401": {
"description": "Invalid API key"
}
},
"tags": [
"Workspace API - Apps"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/batch": {
"post": {
"operationId": "WorkspaceAppsController_batchCreateApps",
"summary": "Batch create apps",
"description": "Create multiple applications at once in the workspace",
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchCreateAppsDto"
}
}
}
},
"responses": {
"201": {
"description": "Apps created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceBatchCreateAppsResponseDto"
}
}
}
},
"401": {
"description": "Invalid API key"
}
},
"tags": [
"Workspace API - Apps"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/{id}/redirect-uris": {
"get": {
"operationId": "WorkspaceAppsController_getRedirectUris",
"summary": "Get redirect URIs",
"description": "Get the redirect URIs for an application",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Redirect URIs retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateRedirectUrisDto"
}
}
}
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Apps"
],
"security": [
{
"workspace-api-key": []
}
]
},
"put": {
"operationId": "WorkspaceAppsController_updateRedirectUris",
"summary": "Update redirect URIs",
"description": "Update the redirect URIs for an application",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateRedirectUrisDto"
}
}
}
},
"responses": {
"200": {
"description": "Redirect URIs updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceAppDto"
}
}
}
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Apps"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/{id}/webhook-config": {
"get": {
"operationId": "WorkspaceAppsController_getWebhookConfig",
"summary": "Get webhook configuration",
"description": "Get the webhook configuration for an application",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Webhook configuration retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWebhookConfigDto"
}
}
}
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Apps"
],
"security": [
{
"workspace-api-key": []
}
]
},
"patch": {
"operationId": "WorkspaceAppsController_updateWebhookConfig",
"summary": "Update webhook configuration",
"description": "Update webhook configuration for an application",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWebhookConfigDto"
}
}
}
},
"responses": {
"200": {
"description": "Webhook configuration updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceAppDto"
}
}
}
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Apps"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/{id}/webhook-config/rotate-secret": {
"post": {
"operationId": "WorkspaceAppsController_rotateWebhookSecret",
"summary": "Rotate webhook secret",
"description": "Generate a new webhook secret for an application",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Webhook secret rotated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"secret": {
"type": "string",
"example": "whsec_..."
}
}
}
}
}
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Apps"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/{id}/providers": {
"get": {
"operationId": "WorkspaceAppsController_listProviders",
"summary": "List activation summaries for all providers on an app",
"description": "Returns a lightweight per-provider activation state summary for every provider that has been enabled on the app. Useful for rendering a multi-provider dashboard without N round-trips. For detailed per-step info, call GET /apps/:id/providers/:providerId/activation/steps.",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListAppProvidersResponseDto"
}
}
}
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Apps"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/{id}": {
"get": {
"operationId": "WorkspaceAppsController_getApp",
"summary": "Get app details",
"description": "Retrieve details of a specific application",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "App details retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceAppDto"
}
}
}
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Apps"
],
"security": [
{
"workspace-api-key": []
}
]
},
"patch": {
"operationId": "WorkspaceAppsController_patchApp",
"summary": "Patch app",
"description": "Partially update an existing application configuration (name, redirect URIs, webhook, default redirects)",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAppDto"
}
}
}
},
"responses": {
"200": {
"description": "App updated successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceAppDto"
}
}
}
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Apps"
],
"security": [
{
"workspace-api-key": []
}
]
},
"delete": {
"operationId": "WorkspaceAppsController_deleteApp",
"summary": "Delete app",
"description": "Delete an application from the workspace",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "App deleted successfully"
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Apps"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/{id}/providers/{providerId}/activation/steps": {
"get": {
"operationId": "WorkspaceActivationController_getActivationSteps",
"summary": "Get activation steps",
"description": "Get computed activation steps for a specific provider",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "providerId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Activation steps retrieved successfully"
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Activation"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/{id}/providers/{providerId}/activation": {
"patch": {
"operationId": "WorkspaceActivationController_enableProvider",
"summary": "Enable or disable provider",
"description": "Enable or disable a provider",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "providerId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceEnableProviderBodyDto"
}
}
}
},
"responses": {
"200": {
"description": "Provider updated successfully"
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Activation"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/{id}/providers/{providerId}/activation/form": {
"post": {
"operationId": "WorkspaceActivationController_submitActivationForm",
"summary": "Submit activation form",
"description": "Submit the activation request form for provider activation",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "providerId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceSubmitActivationFormDto"
}
}
}
},
"responses": {
"201": {
"description": "Activation form submitted successfully",
"headers": {
"Location": {
"description": "URL of the submitted activation form.",
"schema": {
"type": "string",
"format": "uri-reference"
}
}
}
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Activation"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/{id}/providers/{providerId}/activation/documents": {
"post": {
"operationId": "WorkspaceActivationController_uploadDocuments",
"summary": "Upload activation documents",
"description": "Upload documents required for provider activation",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "providerId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"responses": {
"201": {
"description": "Document uploaded successfully"
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App not found"
}
},
"tags": [
"Workspace API - Activation"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/{id}/providers/{providerId}/activation/documents/{documentId}": {
"delete": {
"operationId": "WorkspaceActivationController_deleteDocument",
"summary": "Delete an activation document",
"description": "Remove an uploaded activation document. Deletion is blocked once the document has been processed (approved) by review.",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "providerId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "documentId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Document deleted successfully"
},
"401": {
"description": "Invalid API key"
},
"404": {
"description": "App or document not found"
},
"409": {
"description": "Document has already been processed and cannot be deleted"
}
},
"tags": [
"Workspace API - Activation"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/{id}/workflows/node-types": {
"get": {
"operationId": "WorkspaceWorkflowController_getNodeTypes",
"summary": "List available node types",
"description": "Returns all available flow node types with their fields and placement constraints.",
"parameters": [],
"responses": {
"200": {
"description": "Node type catalog"
}
},
"tags": [
"Workspace API - Workflows"
],
"security": [
{
"workspace-api-key": []
}
]
}
},
"/v1/apps/{id}/workflows": {
"post": {
"operationId": "WorkspaceWorkflowController_createWorkflow",
"summary": "Create a workflow",
"description": "Create a new workflow for the app. Provider keys in `providers` must exist in `app.providers`. Maximum 100 workflows per app. If `workflowId` is omitted, it is auto-generated from `name`.",
"parameters": [
{
"name": "id",
"required": true,
"in": "path",
"description": "App client ID",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWorkflowDto"
}
}
}
},
"responses": {
"201": {
"description": "Workflow created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowResponseDto"
}
}
},
"headers": {
"Location": {
"description": "URL of the newly created workflow.",
"schema": {
"type": "string",
"format": "uri-reference"
}
}
}
},
"400": {
"description": "Validation error (invalid provider key, max limit reached)"
},
"404": {
"description": "App not found"
},
"409": {
"description": "Workflow ID already exists"
# --- truncated at 32 KB (147 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hopae-inc/refs/heads/main/openapi/hopae-inc-hconnect-openapi-original.json