OpenAPI Specification
openapi: 3.0.0
info:
title: hConnect Console - API Keys Workspace API - Apps 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: Workspace API - Apps
description: App management
paths:
/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}/rotate-client-secret:
post:
description: Generates a new clientSecret for the App. The old secret is immediately invalidated. The new secret is returned exactly once.
operationId: WorkspaceAppsController_rotateClientSecret
parameters:
- in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/RotateClientSecretResponseDto'
description: New clientSecret generated
'401':
description: Invalid API key
'404':
description: App not found
security:
- workspace-api-key: []
summary: Rotate client secret
tags:
- Workspace API - Apps
components:
schemas:
PaginatedAppsResponseDto:
type: object
properties:
data:
type: array
items:
type: object
total:
type: number
limit:
type: number
offset:
type: number
required:
- data
- total
- limit
- offset
WorkflowEntryDto:
type: object
properties:
workflowId:
type: string
name:
type: string
entryNodeId:
type: string
nodes:
type: array
items:
$ref: '#/components/schemas/FlowNodeDto'
createdAt:
format: date-time
type: string
updatedAt:
format: date-time
type: string
required:
- workflowId
- name
- entryNodeId
- nodes
FlowNodeDto:
type: object
properties:
id:
type: string
example: nd_ab12cd34
type:
type: string
enum:
- request
- response
- verification
- check-min-loa
- check-claim
- evaluate
- if
next:
type: object
description: 'Next: string (single output) or NextRoute[] (IF branching)'
config:
type: object
description: Type-specific configuration (max depth 5, max 50 keys per level)
required:
- id
- type
WebhookConfigDto:
type: object
properties:
url:
type: string
enabled:
type: boolean
default: true
retryAttempts:
type: number
default: 3
timeoutSeconds:
type: number
default: 10
secret:
type: string
description: Redacted preview of the webhook signing secret in GET responses (e.g., whsec_****abc1). The full value is returned exactly once by POST /webhook-config/rotate-secret.
events:
default: []
type: array
items:
type: string
required:
- enabled
- retryAttempts
- timeoutSeconds
- events
ListAppProvidersResponseDto:
type: object
properties:
providers:
description: Activation state summaries for each provider that has been enabled on the app. Providers that have never been touched are not included. For detailed per-step info, call GET /apps/:id/providers/:providerId/activation/steps.
type: array
items:
$ref: '#/components/schemas/AppProviderSummaryDto'
total:
type: number
example: 3
description: Total number of providers in this response
required:
- providers
- total
CreateAppDto:
type: object
properties:
name:
type: string
required:
- name
WorkspaceAppDto:
type: object
properties:
name:
type: string
logo:
type: string
description: App-level brand logo (base64 data URL)
redirectUris:
type: array
items:
type: string
clientId:
type: string
clientSecret:
type: string
providers:
type: object
description: Contract-level provider configurations. Key = provider ID.
example:
bankidse:
enabled: true
config: {}
frejaid:
enabled: false
config: {}
defaultWorkflowId:
type: string
example: default
description: ID of the default workflow used when workflow_id is not specified
workflows:
description: Workflow profiles for the app
type: array
items:
$ref: '#/components/schemas/WorkflowEntryDto'
organizationId:
type: string
webhookConfig:
$ref: '#/components/schemas/WebhookConfigDto'
defaultSuccessRedirectUri:
type: string
defaultFailureRedirectUri:
type: string
createdAt:
format: date-time
type: string
updatedAt:
format: date-time
type: string
required:
- name
- redirectUris
- clientId
- clientSecret
- providers
- defaultWorkflowId
- workflows
- organizationId
- createdAt
- updatedAt
BatchCreateAppsDto:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/BatchCreateAppItemDto'
continueOnError:
type: boolean
default: false
required:
- items
WorkspaceBatchCreateAppsResponseDto:
type: object
properties:
results:
type: array
items:
type: object
successCount:
type: number
errorCount:
type: number
required:
- results
- successCount
- errorCount
RotateClientSecretResponseDto:
type: object
properties:
clientSecret:
type: string
description: The newly generated clientSecret. Persist immediately; cannot be retrieved later.
example: a3f2c1e4b8d7f6a9c2e5b1d4f7a0c3e6b9d2f5a8c1e4b7d0f3a6c9e2b5d8f1a4
required:
- clientSecret
AppProviderSummaryDto:
type: object
properties:
providerId:
type: string
example: mitid
description: Provider identifier
enabled:
type: boolean
example: true
description: Whether the provider is enabled on this app
state:
type: string
enum:
- not_started
- in_progress
- completed
example: completed
description: Overall activation state derived from step completion
currentStep:
type: string
example: activated
description: The type key of the current activation step
currentStepIndex:
type: number
example: 3
description: Zero-based index of the current step in the step sequence
stepCount:
type: number
example: 4
description: Total number of steps in this provider's activation sequence
required:
- providerId
- enabled
- state
- currentStep
- currentStepIndex
- stepCount
UpdateAppDto:
type: object
properties:
name:
type: string
logo:
type: string
description: App-level brand logo (base64 data URL). Pass an empty string to remove the logo.
redirectUris:
type: array
items:
type: string
webhookConfig:
$ref: '#/components/schemas/WebhookConfigDto'
defaultSuccessRedirectUri:
type: string
defaultFailureRedirectUri:
type: string
BatchCreateAppItemDto:
type: object
properties:
name:
type: string
redirectUris:
type: array
items:
type: string
webhookConfig:
$ref: '#/components/schemas/WebhookConfigDto'
idempotencyKey:
type: string
required:
- name
UpdateWebhookConfigDto:
type: object
properties:
url:
type: string
enabled:
type: boolean
retryAttempts:
type: number
timeoutSeconds:
type: number
events:
type: array
items:
type: string
UpdateRedirectUrisDto:
type: object
properties:
redirectUris:
type: array
items:
type: string
required:
- redirectUris
securitySchemes:
basicAuth:
type: http
scheme: basic
description: 'Basic authentication using clientId and clientSecret. For direct API calls, format the Authorization header as `Authorization: Basic <base64(clientId:clientSecret)>`. In the Mintlify playground, enter the clientId and clientSecret in the Basic Auth panel and the header is generated automatically.'
workspaceApiKey:
type: http
scheme: bearer
bearerFormat: API Key
description: 'Workspace API key authentication. Pass your workspace API key as `Authorization: Bearer sk_workspace_...`.'
consoleJwt:
type: http
scheme: bearer
bearerFormat: JWT
description: Console JWT authentication. Issued by Clerk after Console login.
workspace-api-key:
scheme: bearer
bearerFormat: JWT
type: http
app-basic:
type: http
scheme: basic