> For the complete documentation index, see [llms.txt](https://docs.credebl.id/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.credebl.id/docs/references/platform-apis/ecosystem/ecosystem-apis.md). # Ecosystem APIs ## 1. Overview The platform is organized into three functional layers, each building upon the one below it:
LayerWhat it contains
Users & OrganizationsPlatform users and the organizations they own and manage
EcosystemsGroups of organizations governed and coordinated by an ecosystem lead
Trust ServiceA centralized registry of trusted entities and their associated X.509 certificates
Users own organizations; organizations can form or join ecosystems; and ecosystems publish trust lists that are consumed during credential issuance and verification workflows. ## 2. Users & Organizations The platform supports multiple concurrent users. Each user can create and own one or more organizations, each operating as a fully independent unit. Every organization is capable of: * Creating and managing its own **digital wallet** * **Issuing** verifiable credentials to holders * **Verifying** credentials presented by holders during interactions ``` Platform Admin ├── User A │ ├── Org 1 (Wallet · Issue · Verify) │ └── Org 2 (Wallet · Issue · Verify) └── User B ├── Org 3 (Wallet · Issue · Verify) └── Org 4 (Wallet · Issue · Verify) ``` ## 3. Ecosystems An ecosystem is a governed network of organizations coordinated by an **ecosystem lead**. The platform admin initiates this process by designating an organizations as the ecosystem lead. The formation process works in two stages: {% stepper %} {% step %} ### Platform Admin → Organizations The platform administrator sends an invitation to a specific organization, designating it as the ecosystem lead. {% endstep %} {% step %} ### Ecosystem Lead → Member Organizations Once the invitation is accepted, the ecosystem lead can invite other organizations to join as **ecosystem members**. {% endstep %} {% endstepper %} An organization that receives a membership invitation may either: * **Accept** - and become an active ecosystem member, gaining access to the ecosystem's shared trust data and workflows. * **Reject** - and remain outside the ecosystem, with no access to its resources. An ecosystem can include any number of member organizations, enabling large-scale, multi-party credential workflows. ``` Platform Admin │ (sends ecosystem invitation) ▼ Ecosystem Lead Org ├── Member Org 1 ← Accepted invitation ├── Member Org 2 ← Accepted invitation └── Org C ← Rejected (not a member) ``` ### 3.1. Ecosystem API Reference This section documents the core API endpoints available for managing ecosystems and their memberships. #### 3.1.1 Create Ecosystem Invitation (Platform Admin) This endpoint allows the platform administrator to invite a user (by email) to create and lead a new ecosystem. **Endpoint** ``` POST /v1/invitations ``` **Request Body** ```json { "email": "user@example.com" } ``` **Response** ```json { "statusCode": 201, "message": "Ecosystem created successfully", "data": { "id": "{invitationId}", "name": "ecosystem 1", "description": "ecosystem 1", "tags": null, "autoEndorsement": false, "logoUrl": null, "createdBy": "{userId}", "createDateTime": "2026-02-05T11:24:03.046Z" } } ``` > **Note:** The platform admin can also fetch all ecosystem invitations created by the currently authenticated user using the appropriate listing endpoint. #### 3.1.2 Create Ecosystem Once invited, the designated organization uses this endpoint to formally create and configure the ecosystem. > **Role required:** Organization Owner **Endpoint** ``` POST /v1/ecosystem/{orgId}/create ``` **Request Body** ```json { "name": "ecosystem 1", "description": "ecosystem 1" } ``` **Response** ```json { "statusCode": 201, "message": "Ecosystem invitations sent" } ``` #### 3.1.3 Invite Organizations Once the ecosystem is established, the ecosystem lead can invite other platform organizations to join as members. This endpoint initiates a membership invitation for a specific organization. > **Role required:** Ecosystem Lead **Endpoint** ``` POST /v1/ecosystem/invite-member ``` **Request Body** ```json { "orgId": "{orgId}", "ecosystemId": "{ecosystemId}" } ``` **Response** ```json { "statusCode": 201, "message": "Invitation sent successfully for the member" } ``` **Check Invitation Status** To review the list of pending or accepted invitations within an ecosystem, use the following endpoint: ``` GET /v1/ecosystem/invitations?orgId={ecosystemId}&pageNumber=1&pageSize=10&role=Ecosystem%20Member ``` #### 3.1.4 Accept or Reject Invitation The organization owner uses this endpoint to respond to a received ecosystem membership invitation. Upon acceptance, the organization gains access to the ecosystem's shared trust data and can view all other member organizations. > **Role required:** Ecosystem Member **Endpoint** ``` POST /v1/ecosystem/update-invitation-status ``` **Request Body** ```json { "status": "accepted", "ecosystemId": "{ecosystemId}" } ``` **Response** ```json { "statusCode": 200, "message": "Status for ecosystem invitation updated successfully as accepted" } ``` **View Member Organizations** Once an organization has accepted the invitation, it can retrieve the full list of organizations that have joined the same ecosystem using the following endpoint: ``` GET /v1/ecosystem/get-ecosystem-orgs ``` #### 3.1.5 Get Ecosystem Invitations
Fetch all the invitation’s sent by platform admin > **Role required:** Platform Admin ``` GET v1/invitations?pageNumber=1&pageSize=10 ``` ```json { "statusCode": 200, "message": "Ecosystem invitations fetched successfully", "data": { "totalPages": 1, "data": [ { "id": "72d6fa97-42b6-46df-bd92-df44e5d8ebd7", "email": "testuser@yopmail.com", "status": "accepted", "userId": "c7e85d96-4bcc-4f6a-8d76-ae977daf0c43", "type": "ecosystem", "ecosystemId": "0eae279b-1a4e-4f37-9472-4742cd7233c6", "invitedOrg": "1a574a6b-f535-4197-ab4c-a8d2fcb3d139", "createDateTime": "2026-05-06T07:07:18.545Z", "createdBy": "b1f6b53c-9155-40c2-96a9-9cb144dafe49", "lastChangedDateTime": "2026-05-06T07:07:18.545Z", "lastChangedBy": "b1f6b53c-9155-40c2-96a9-9cb144dafe49", "deletedAt": null, "ecosystem": { "id": "0eae279b-1a4e-4f37-9472-4742cd7233c6", "name": "Test Eco", "description": "description", "createDateTime": "2026-05-06T07:07:41.360Z" }, "organisation": { "name": "Other Wallet" } } ] } } ``` #### 3.1.6 Check if Ecosystem feature is enabled/disabled ``` GET /v1/ecosystem/status ``` Used for checking the Ecosystem feature if enabled or disabled #### 3.1.7 Overview Summary for platform admin ``` GET /v1/ecosystem/dashboard/summary ``` > **Role required:** Platform Admin Provides a summary count for actions performed in Admin portal ```json { "statusCode": 200, "message": "Dashboard data for ecosystem fetched successfully", "data": { "ecosystem": 1, "invitations": 1, "activeOrgs": 1 } } ``` #### 3.1.8 Get all Ecosystem’s for Organizations Fetch all ecosystem’s related to the organization may it be a ecosystem member or ecosystem Lead. ``` GET /v1/ecosystem ``` ```json { "statusCode": 200, "message": "All Ecosystems fetched successfully", "data": { "totalPages": 1, "data": [ { "id": "0eae279b-1a4e-4f37-9472-4742cd7233c6", "name": "Zxaes", "description": "Zwe sd", "memberCount": 1, "role": "Ecosystem Lead", "leadOrg": { "id": "1a574a6b-f535-4197-ab4c-a8d2fcb3d139", "name": "Other Wallet" } } ] } } ``` #### 3.1.9 Get Ecosystem Members > **Role required:** Ecosystem Lead Fetch all member’s belonging to a particular ecosystem. ``` GET /v1/ecosystem/members ``` ```json { "statusCode": 200, "message": "Ecosystem members fetched successfully", "data": { "totalPages": 1, "data": [ { "id": "eeea0842-9054-450a-9c98-49dff6968681", "status": "ACTIVE", "createDateTime": "2026-05-06T08:22:54.449Z", "ecosystem": { "id": "0eae279b-1a4e-4f37-9472-4742cd7233c6", "name": "Zxaes" }, "organisation": { "id": "b0105fc4-f9b2-43ab-b069-a659d239a55b", "name": "Member org" }, "user": { "id": "ed4cfec4-7328-419c-9986-5c5679514c5b", "email": "Testuser@yopmail.com" } } ] } } ``` ### 3.2. Intent An **Intent** represents a named business workflow or use case within an ecosystem - for example, "Airport Boarding" or "Age Verification at a Venue." Ecosystem leads define intents to establish the purpose and context of credential-based interactions, enabling all participating organizations to align on the goals of each workflow. Each intent can optionally have: * An **Intent Template** - defining which credential templates are required as part of this workflow (section 3.2.5). * An **Intent Notice** - a formal consent notice informing data subjects of how their personal data will be processed (section 3.2.6). #### 3.2.1 Create Intent Creates a new intent within the specified ecosystem. > **Role required:** Ecosystem Lead **Endpoint** ``` POST /v1/intent/ecosystem/{ecosystemId} ``` **Request Body** ```json { "name": "Boarding", "description": "Boarding pass intent" } ``` **Response** ```json { "statusCode": 201, "message": "Ecosystem intent created successfully", "data": { "id": "{intentId}", "ecosystemId": "{ecosystemId}", "name": "Boarding", "description": "Boarding pass intent", "createDateTime": "2026-03-30T08:39:25.118Z", "createdBy": "{userId}", "lastChangedDateTime": "2026-03-30T08:39:25.118Z", "lastChangedBy": "{userId}" } } ``` #### 3.2.2 Get All Intents Retrieves a paginated list of all intents defined within a given ecosystem. Useful for displaying available workflows to ecosystem participants. > **Role required:** Ecosystem Lead **Endpoint** ``` GET /v1/intent/ecosystem/{ecosystemId}?pageNumber=1&pageSize=10 ``` **Query Parameters**
ParameterTypeRequiredDescription
pageNumberintegerNoThe page number to retrieve (default: 1)
pageSizeintegerNoThe number of records per page (default: 10)
**Response** ```json { "statusCode": 200, "message": "Ecosystem intents fetched successfully", "data": { "totalItems": 2, "data": [ { "id": "{intentId}", "ecosystemId": "{ecosystemId}", "name": "Boarding", "description": "Boarding pass intent", "createDateTime": "2026-03-30T08:39:25.118Z", "createdBy": "{userId}", "lastChangedDateTime": "2026-03-30T08:39:25.118Z", "lastChangedBy": "{userId}" } ], "page": 1, "pageSize": 10 } } ``` #### 3.2.3 Get Intent by ID Retrieves the full details of a specific intent using its unique identifier. This is typically used when loading the details of a selected workflow for review or configuration. **Endpoint** ``` GET /v1/intent/{intentId} ``` **Path Parameters**
ParameterTypeRequiredDescription
intentIdUUIDYesThe unique identifier of the intent to retrieve
**Response** ```json { "statusCode": 200, "message": "Ecosystem intent fetched successfully", "data": { "id": "{intentId}", "ecosystemId": "{ecosystemId}", "name": "Boarding", "description": "Boarding pass intent", "createDateTime": "2026-03-30T08:39:25.118Z", "createdBy": "{userId}", "lastChangedDateTime": "2026-03-30T08:39:25.118Z", "lastChangedBy": "{userId}" } } ``` #### 3.2.4 Update Intent Updates the name or description of an existing intent. This endpoint allows the ecosystem lead to refine a workflow definition after it has been created. > **Role required:** Ecosystem Lead **Endpoint** ``` PUT /v1/intent/{intentId} ``` **Path Parameters**
ParameterTypeRequiredDescription
intentIdUUIDYesThe unique identifier of the intent to update
**Request Body** ```json { "name": "Boarding Updated", "description": "Updated boarding pass workflow for international flights" } ``` **Response** ```json { "statusCode": 200, "message": "Ecosystem intent updated successfully", "data": { "id": "{intentId}", "ecosystemId": "{ecosystemId}", "name": "Boarding Updated", "description": "Updated boarding pass workflow for international flights", "createDateTime": "2026-03-30T08:39:25.118Z", "createdBy": "{userId}", "lastChangedDateTime": "2026-03-31T10:00:00.000Z", "lastChangedBy": "{userId}" } } ``` #### 3.2.5 Intent Template An **Intent Template** links one or more credential templates to a specific intent, defining which credential types are required as part of that workflow. For example, the "Boarding" intent may require a Passport (Photo ID) credential template to be presented and verified at the gate. Ecosystem leads use these endpoints to associate, retrieve, and update the credential templates tied to a given intent. **3.2.5.1 Create Intent Template (Map intent to template)** Associates a credential template with a specific intent. > **Role required:** Ecosystem Lead **Endpoint** ``` POST /v1/intent/{intentId}/template ``` **Path Parameters**
ParameterTypeRequiredDescription
intentIdUUIDYesThe unique identifier of the intent to which the template is to be linked
**Request Body** ```json { "templateId": "{templateId}", "role": "verifier", "description": "Passport credential required for boarding gate verification" } ``` **Key Fields**
FieldDescription
templateIdThe unique identifier of the credential template to associate with this intent
roleThe role this template serves within the intent: issuer or verifier
descriptionAn optional description of why this template is required in this workflow
**Response** ```json { "statusCode": 201, "message": "Intent template created successfully", "data": { "id": "{intentTemplateId}", "intentId": "{intentId}", "templateId": "{templateId}", "role": "verifier", "description": "Passport credential required for boarding gate verification", "createDateTime": "2026-03-30T09:00:00.000Z", "createdBy": "{userId}" } } ``` **3.2.5.2 Get Intent Templates** Retrieves all credential templates associated with a specific intent. This is used to determine which credentials are required or expected within a given workflow. > **Role required:** Ecosystem Lead **Endpoint** ``` GET /v1/intent/{intentId}/template ``` **Path Parameters**
ParameterTypeRequiredDescription
intentIdUUIDYesThe unique identifier of the intent whose templates are to be retrieved
**Response** ```json { "statusCode": 200, "message": "Intent templates fetched successfully", "data": [ { "id": "{intentTemplateId}", "intentId": "{intentId}", "templateId": "{templateId}", "role": "verifier", "description": "Passport credential required for boarding gate verification", "createDateTime": "2026-03-30T09:00:00.000Z", "lastChangedDateTime": "2026-03-30T09:00:00.000Z" } ] } ``` **3.2.5.3 Update Intent Template** Updates the role or description of a credential template already associated with an intent. Use this endpoint when the purpose or usage of a template within a workflow changes. > **Role required:** Ecosystem Lead **Endpoint** ``` PUT /v1/intent/{intentId}/template/{intentTemplateId} ``` **Path Parameters**
ParameterTypeRequiredDescription
intentIdUUIDYesThe unique identifier of the intent
intentTemplateIdUUIDYesThe unique identifier of the intent-template association to update
**Request Body** ```json { "role": "issuer", "description": "Updated: Passport credential issued during check-in" } ``` **Response** ```json { "statusCode": 200, "message": "Intent template updated successfully", "data": { "id": "{intentTemplateId}", "intentId": "{intentId}", "templateId": "{templateId}", "role": "issuer", "description": "Updated: Passport credential issued during check-in", "lastChangedDateTime": "2026-03-31T12:00:00.000Z" } } ``` #### 3.2.6 Intent Notice An **Intent Notice** is a formal consent notice linked to a specific intent. It informs data subjects of how their personal data will be collected, processed, and used within the context of a particular ecosystem workflow. Each intent can have one associated notice. The intent notice is aligned with **ISO/IEC TS 27560** and the **Data Privacy Vocabulary (DPV)** standards, ensuring compliance with global best practices for privacy and consent management. **3.2.6.1 Create Intent Notice (Map intent to notice)** Creates a new consent notice and associates it with a specific intent. > **Role required:** Ecosystem Lead **Endpoint** ``` POST /v1/intent/{intentId}/notice ``` **Path Parameters**
ParameterTypeRequiredDescription
intentIdUUIDYesThe unique identifier of the intent to which the notice is to be linked
**3.2.6.2 Get Intent Notice by Intent ID** Retrieves the consent notice associated with a specific intent. This endpoint is used to display the current notice to participants or to review its contents before issuance or verification. > **Role required:** Ecosystem Lead and Member **Endpoint** ``` GET /v1/intent/{intentId}/notice ``` **Path Parameters**
ParameterTypeRequiredDescription
intentIdUUIDYesThe unique identifier of the intent whose notice is to be retrieved
**3.2.6.3 Update Intent Notice** Updates an existing consent notice linked to a specific intent. Use this endpoint when the terms, policies, or data processing rules of a workflow have changed and the notice needs to reflect the latest information. > **Note:** Updating a notice typically results in a new version being issued. Participants who previously accepted the older version may be may not effect, depending on the platform's consent management policy. > **Role required:** Ecosystem Lead and Member **Endpoint** ``` PUT /v1/intent/{intentId}/notice ``` **Path Parameters**
ParameterTypeRequiredDescription
intentIdUUIDYesThe unique identifier of the intent whose notice is to be updated
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.credebl.id/docs/references/platform-apis/ecosystem/ecosystem-apis.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.