Workspace
Apps
Providers
Provider Activation
Redirect URIs
Workflows
curl -H "Authorization: Bearer sk_workspace_test_..." \
"https://sandbox.api.hopae.com/connect/v1/apps/abc123/providers/spid-ig/activation/steps"
{
"providerId": "spid-ig",
"state": "in_progress",
"currentStepIndex": 3,
"steps": [
{
"type": "enable",
"title": "Enable Provider",
"description": "Enable this provider to proceed to the next steps."
},
{
"type": "activation-form",
"title": "Submit Activation Request Form",
"description": "Submit the required information for provider activation.",
"requiredFields": [
{
"label": "Legal Company Name",
"name": "legalCompanyName",
"value": "Acme Corp",
"type": "string",
"example": "Acme Corporation Ltd.",
"helpText": "The registered legal name of the company, as shown on official incorporation documents."
},
{
"label": "Registered Address",
"name": "registeredAddress",
"value": "9 Boulevard Prince Henri, L-1724 Luxembourg",
"type": "string",
"example": "9 Boulevard Prince Henri, L-1724 Luxembourg",
"helpText": "Full registered business address including street, city, postal code, and country."
},
{
"label": "VAT Number",
"name": "vatNumber",
"value": "LU12345678",
"type": "string",
"example": "DE123456789",
"helpText": "The EU VAT identification number, including the country prefix."
},
{
"label": "Registration Number",
"name": "registrationNumber",
"value": "12345678",
"type": "string",
"example": "B123456",
"helpText": "The company registration number from your country's business registry (e.g., RCS Luxembourg, HRB Germany, CVR Denmark)."
},
{
"label": "Service Description",
"name": "serviceDescription",
"value": "Customer identity verification for KYC onboarding.",
"type": "string",
"example": "Acme IDV console — customer identity verification for KYC onboarding.",
"helpText": "One-sentence description of your service, shown during provider activation review."
},
{
"label": "User Data Level",
"name": "userDataLevel",
"value": "basic",
"type": "string",
"options": [
{
"value": "basic",
"description": "Basic: name, surname, fiscal code, and date of birth"
},
{
"value": "advanced",
"description": "Advanced: all basic attributes plus place of birth, gender, ID document details, phone number, email, and registered address"
}
],
"helpText": "Italian SPID data retrieval scope. 'basic' is sufficient for age/identity verification; 'advanced' adds place of birth and document details."
},
{
"label": "Logo",
"name": "logo",
"value": "data:image/png;base64,iVBORw0KGgo...",
"type": "base64",
"example": "data:image/png;base64,iVBORw0KGgo...",
"helpText": "Base64-encoded PNG or SVG logo (max 256KB). Used for branding in provider-facing consent screens."
},
{
"label": "Contact Email",
"name": "contactEmail",
"value": "compliance@acme.com",
"type": "email",
"example": "ops@acme.com",
"helpText": "Operations contact email — Hopae will use this for activation status notifications."
}
],
"form": {
"id": "fe1ce6d9-90fb-4f42-88ae-4622135c7f19",
"status": "submitted",
"note": ""
}
},
{
"type": "upload",
"title": "Upload Documents",
"description": "Upload the required documents for provider activation.",
"documents": [
{
"label": "SPID Aggregation Agreement",
"templateUrl": "https://static.hopae.com/templates/spid-ig/spid_aggregation_agreement.docx"
}
],
"uploaded": [
{
"documentId": "0567eeb3-eda7-489a-9ba8-84f0ae3f301e",
"fileName": "spid_aggregation_agreement.docx",
"fileSize": 784044,
"contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"uploadedAt": "2026-04-20T02:20:27.521Z",
"state": "pending"
}
]
},
{
"type": "api-key",
"title": "Issuing Production API Key",
"description": "Production API keys are being issued."
},
{
"type": "activated",
"title": "Provider Activated",
"description": "API key has successfully been issued and configured."
}
]
}
Provider Activation
Get Activation Steps
Retrieve the computed activation steps for a specific provider.
GET
/
apps
/
{client_id}
/
providers
/
{provider_id}
/
activation
/
steps
curl -H "Authorization: Bearer sk_workspace_test_..." \
"https://sandbox.api.hopae.com/connect/v1/apps/abc123/providers/spid-ig/activation/steps"
{
"providerId": "spid-ig",
"state": "in_progress",
"currentStepIndex": 3,
"steps": [
{
"type": "enable",
"title": "Enable Provider",
"description": "Enable this provider to proceed to the next steps."
},
{
"type": "activation-form",
"title": "Submit Activation Request Form",
"description": "Submit the required information for provider activation.",
"requiredFields": [
{
"label": "Legal Company Name",
"name": "legalCompanyName",
"value": "Acme Corp",
"type": "string",
"example": "Acme Corporation Ltd.",
"helpText": "The registered legal name of the company, as shown on official incorporation documents."
},
{
"label": "Registered Address",
"name": "registeredAddress",
"value": "9 Boulevard Prince Henri, L-1724 Luxembourg",
"type": "string",
"example": "9 Boulevard Prince Henri, L-1724 Luxembourg",
"helpText": "Full registered business address including street, city, postal code, and country."
},
{
"label": "VAT Number",
"name": "vatNumber",
"value": "LU12345678",
"type": "string",
"example": "DE123456789",
"helpText": "The EU VAT identification number, including the country prefix."
},
{
"label": "Registration Number",
"name": "registrationNumber",
"value": "12345678",
"type": "string",
"example": "B123456",
"helpText": "The company registration number from your country's business registry (e.g., RCS Luxembourg, HRB Germany, CVR Denmark)."
},
{
"label": "Service Description",
"name": "serviceDescription",
"value": "Customer identity verification for KYC onboarding.",
"type": "string",
"example": "Acme IDV console — customer identity verification for KYC onboarding.",
"helpText": "One-sentence description of your service, shown during provider activation review."
},
{
"label": "User Data Level",
"name": "userDataLevel",
"value": "basic",
"type": "string",
"options": [
{
"value": "basic",
"description": "Basic: name, surname, fiscal code, and date of birth"
},
{
"value": "advanced",
"description": "Advanced: all basic attributes plus place of birth, gender, ID document details, phone number, email, and registered address"
}
],
"helpText": "Italian SPID data retrieval scope. 'basic' is sufficient for age/identity verification; 'advanced' adds place of birth and document details."
},
{
"label": "Logo",
"name": "logo",
"value": "data:image/png;base64,iVBORw0KGgo...",
"type": "base64",
"example": "data:image/png;base64,iVBORw0KGgo...",
"helpText": "Base64-encoded PNG or SVG logo (max 256KB). Used for branding in provider-facing consent screens."
},
{
"label": "Contact Email",
"name": "contactEmail",
"value": "compliance@acme.com",
"type": "email",
"example": "ops@acme.com",
"helpText": "Operations contact email — Hopae will use this for activation status notifications."
}
],
"form": {
"id": "fe1ce6d9-90fb-4f42-88ae-4622135c7f19",
"status": "submitted",
"note": ""
}
},
{
"type": "upload",
"title": "Upload Documents",
"description": "Upload the required documents for provider activation.",
"documents": [
{
"label": "SPID Aggregation Agreement",
"templateUrl": "https://static.hopae.com/templates/spid-ig/spid_aggregation_agreement.docx"
}
],
"uploaded": [
{
"documentId": "0567eeb3-eda7-489a-9ba8-84f0ae3f301e",
"fileName": "spid_aggregation_agreement.docx",
"fileSize": 784044,
"contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"uploadedAt": "2026-04-20T02:20:27.521Z",
"state": "pending"
}
]
},
{
"type": "api-key",
"title": "Issuing Production API Key",
"description": "Production API keys are being issued."
},
{
"type": "activated",
"title": "Provider Activated",
"description": "API key has successfully been issued and configured."
}
]
}
Returns the activation steps, current progress, and overall state for a provider. Steps vary by provider.Documentation Index
Fetch the complete documentation index at: https://docs.hopae.com/llms.txt
Use this file to discover all available pages before exploring further.
Request
Bearer <API_KEY> from Console > Developers > Workspace API Keys.Path parameters
Client identifier of the app.
Provider identifier (e.g.,
smartid, ftn, mitid).Response
Echo of the provider identifier from the request path.
Overall activation state:
not_started, in_progress, or completed.Zero-based index of the first incomplete step. Equals the last step index when all steps are completed.
Ordered list of activation steps. Each step contains:
Show Step object
Show Step object
Step identifier:
enable, activation-form, upload, api-key, or activated.Human-readable step title.
Human-readable step description. For the
activation-form step, this is overridden on contract-category providers to describe the out-of-band follow-up.(activation-form step, contract providers only) Present and
true when the provider requires a direct contract with the upstream provider. Signals that clearing the activation-form step does not auto-advance activation — the Hopae team reaches out via the submitted contactEmail to finalize the contract. Use this flag to branch your UI between “self-service” and “awaiting Hopae follow-up” messaging.(activation-form step only) List of required fields for the activation form.
Show Field object
Show Field object
Display label.
Field key used in the
data object of the submit request body.Current value, or empty string if not yet provided.
Data type of the value:
string, base64 (for image/logo fields), email, url, or boolean.Example value illustrating the expected format (e.g.,
"HRB 123456").Short guidance shown to the user explaining what the field expects.
(Optional, advisory) Regex hint for client-side validation. Not currently enforced server-side — rely on
type and options for authoritative checks.(activation-form step only) Previously submitted form details, or
null if no form has been submitted yet.Show Form object
Show Form object
Unique identifier of the submitted form.
Customer-facing review status:
submitted (form received and under review — internal processing and completed states are collapsed to this) or rejected (admin rejected the submission). A rejected form can be resubmitted via Submit Activation Form. Approval is detected by currentStepIndex advancing past the activation-form step, not by a change in form.status.Note attached to the form. Initially carries any user-submitted note; after an admin decision, this is overwritten with the admin’s note (e.g., the rejection reason). Empty string if no note has been set.
(upload step only) Catalog of documents the provider requires. Each entry has a
label describing the document and, where a template is available, a templateUrl to download the form to fill in. An optional: true flag marks documents that are not required for the step to complete.(upload step only) Documents already uploaded against this provider, including their review state. Rejected uploads are retained here (rather than deleted) so clients can surface the reviewer’s rejection note; re-uploading a replacement supersedes them for step-progression purposes.
Show Uploaded document object
Show Uploaded document object
Unique identifier of the uploaded document.
Original file name as submitted.
Size of the file in bytes.
MIME type (e.g.,
application/pdf).ISO 8601 upload timestamp.
Review state:
pending, processed, or rejected. The upload step advances once the count of non-rejected uploads reaches the number of required entries in documents. Rejected uploads do not count toward that total — re-upload a replacement via Upload Activation Documents to move past a rejection.(Optional) Catalog entry the upload corresponds to (matches a
documents[].label). Populated only for uploads originated from the Hopae Console; absent for uploads made through this Workspace API — correlate by fileName instead.Review note from the Hopae team. After a rejection, this contains the reviewer’s reason.
ISO 8601 timestamp of the most recent review decision, if any.
curl -H "Authorization: Bearer sk_workspace_test_..." \
"https://sandbox.api.hopae.com/connect/v1/apps/abc123/providers/spid-ig/activation/steps"
{
"providerId": "spid-ig",
"state": "in_progress",
"currentStepIndex": 3,
"steps": [
{
"type": "enable",
"title": "Enable Provider",
"description": "Enable this provider to proceed to the next steps."
},
{
"type": "activation-form",
"title": "Submit Activation Request Form",
"description": "Submit the required information for provider activation.",
"requiredFields": [
{
"label": "Legal Company Name",
"name": "legalCompanyName",
"value": "Acme Corp",
"type": "string",
"example": "Acme Corporation Ltd.",
"helpText": "The registered legal name of the company, as shown on official incorporation documents."
},
{
"label": "Registered Address",
"name": "registeredAddress",
"value": "9 Boulevard Prince Henri, L-1724 Luxembourg",
"type": "string",
"example": "9 Boulevard Prince Henri, L-1724 Luxembourg",
"helpText": "Full registered business address including street, city, postal code, and country."
},
{
"label": "VAT Number",
"name": "vatNumber",
"value": "LU12345678",
"type": "string",
"example": "DE123456789",
"helpText": "The EU VAT identification number, including the country prefix."
},
{
"label": "Registration Number",
"name": "registrationNumber",
"value": "12345678",
"type": "string",
"example": "B123456",
"helpText": "The company registration number from your country's business registry (e.g., RCS Luxembourg, HRB Germany, CVR Denmark)."
},
{
"label": "Service Description",
"name": "serviceDescription",
"value": "Customer identity verification for KYC onboarding.",
"type": "string",
"example": "Acme IDV console — customer identity verification for KYC onboarding.",
"helpText": "One-sentence description of your service, shown during provider activation review."
},
{
"label": "User Data Level",
"name": "userDataLevel",
"value": "basic",
"type": "string",
"options": [
{
"value": "basic",
"description": "Basic: name, surname, fiscal code, and date of birth"
},
{
"value": "advanced",
"description": "Advanced: all basic attributes plus place of birth, gender, ID document details, phone number, email, and registered address"
}
],
"helpText": "Italian SPID data retrieval scope. 'basic' is sufficient for age/identity verification; 'advanced' adds place of birth and document details."
},
{
"label": "Logo",
"name": "logo",
"value": "data:image/png;base64,iVBORw0KGgo...",
"type": "base64",
"example": "data:image/png;base64,iVBORw0KGgo...",
"helpText": "Base64-encoded PNG or SVG logo (max 256KB). Used for branding in provider-facing consent screens."
},
{
"label": "Contact Email",
"name": "contactEmail",
"value": "compliance@acme.com",
"type": "email",
"example": "ops@acme.com",
"helpText": "Operations contact email — Hopae will use this for activation status notifications."
}
],
"form": {
"id": "fe1ce6d9-90fb-4f42-88ae-4622135c7f19",
"status": "submitted",
"note": ""
}
},
{
"type": "upload",
"title": "Upload Documents",
"description": "Upload the required documents for provider activation.",
"documents": [
{
"label": "SPID Aggregation Agreement",
"templateUrl": "https://static.hopae.com/templates/spid-ig/spid_aggregation_agreement.docx"
}
],
"uploaded": [
{
"documentId": "0567eeb3-eda7-489a-9ba8-84f0ae3f301e",
"fileName": "spid_aggregation_agreement.docx",
"fileSize": 784044,
"contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"uploadedAt": "2026-04-20T02:20:27.521Z",
"state": "pending"
}
]
},
{
"type": "api-key",
"title": "Issuing Production API Key",
"description": "Production API keys are being issued."
},
{
"type": "activated",
"title": "Provider Activated",
"description": "API key has successfully been issued and configured."
}
]
}
⌘I