--- title: Using the Bpanda API description: >- Bpanda's REST interface for integrations: which license and which API client (a technical user with a Client ID and Client Secret) you need, how to obtain a token — and which information from your CMDB, ERP, GRC or project tools you can link to your processes. search: tags: - api - rest - integration - schnittstelle --- Through the Public API, your IT creates information from other systems as architecture elements in Bpanda and links it to processes. It also reads process information, organizational structure, users and groups. Each operation has its own page in the [API Reference](/en/api-reference) — with parameters, response format, code examples and a **Try it** section. This article explains what to do beforehand, how authentication works and what the API is useful for. ## Prerequisites [#prerequisites] - **API license.** Your account needs the license for the API. It is activated by the Customer Success team: [wecare@mid.de](mailto:wecare@mid.de). - **API client.** You create it yourself in the **Account Management**: in the **Account Users** section via ⋮ **Add New API User**, see [Managing Account Users](/en/settings/manage-account/manage-account-users). It consists of a **Client ID** and a **Client Secret** and acts in Bpanda as a technical user — the API user. You only see the secret when creating the client — keep it as safe as a password. - **A Bpanda license for the API user.** In addition to the API license, the API user is assigned a regular Bpanda license in the Account Management, just like any other user. This gives the API user **read access** to the Process Space. - **A Bpanda role**, if the API user needs to do more. Only **BPM Managers** and **Designers** may create, import and publish architecture elements. The role an operation requires is listed on its page in the reference under **Security**. You assign the role as you would for any other user, see [Assigning Users and Bpanda Roles](/en/settings/manage-process-space/assigning-users-and-roles) and [Defining Designers and BPM Managers](/en/settings/manage-account/process-designers-and-bpm-managers). - **Account ID.** It appears in the path of the Account Management as soon as you have opened your account. ## How to Authenticate [#how-to-authenticate] Authentication is a single call without a prior token: [apiUserInfo](/en/api-reference/api-authorization/api-user-info-get-api-user-info). You pass the Account ID, Client ID and Client Secret and receive everything the subsequent calls need. The base address of your environment is shown in every code example in the reference. ```bash curl curl -X POST https:///bpm/api/v1/apiUserInfo -H "Content-Type: application/json" -d "{\"accountId\":\"\",\"clientId\":\"\",\"clientSecret\":\"\"}" ``` ```powershell PowerShell $body = @{ accountId = ""; clientId = ""; clientSecret = "" } | ConvertTo-Json Invoke-RestMethod -Method Post -Uri "https:///bpm/api/v1/apiUserInfo" -ContentType "application/json" -Body $body ``` The response contains five fields: | Field | Meaning | | --- | --- | | `token` | the access token — sent as `Authorization: Bearer ` in every call | | `licenseToken` | the license token — sent as `BpmLicense: ` in every call | | `processSpaceId` | your Process Space — the value for the path parameter `warehouseId` | | `userId`, `email` | the API user under which the API client operates | A first call that reads [all users of the Process Space](/en/api-reference/users/users-get-all-users) looks like this: ```bash curl curl https:///bpm/api/v1/warehouses//users -H "Authorization: Bearer " -H "BpmLicense: " ``` ```powershell PowerShell Invoke-RestMethod -Uri "https:///bpm/api/v1/warehouses//users" -Headers @{ Authorization = "Bearer "; BpmLicense = "" } ``` If authentication responds with **404 "No license token found"**, the account lacks the API license. With **429** you have made too many calls in a short time — wait briefly and repeat the call. If the access token expires, simply call the authentication again — there is no separate refresh mechanism. ## Linking Information from Other Systems to Processes [#linking-information-from-other-systems-to-processes] The API is most valuable when you link information from other systems to your processes. You then see, for example, which applications a process uses, which requirements it implements or which project changes it. You create this information in Bpanda as architecture elements: Bpanda knows the element types of all layers of ArchiMate® 3.2, and each element can be linked to processes. You evaluate the links in Bpanda afterwards, see [Available Reports](/en/architecture/reports/list-available-reports). The following overview is organized by tool category. For each category, it shows what the system holds, which element types in Bpanda this data corresponds to, and which questions you can answer once you link it to processes. **IT Service Management, CMDB** ServiceNow, i-doit, Matrix42 - **The system holds:** applications, servers, services, interfaces - **In Bpanda:** Application Component, Application Service, Application Interface, Node, System Software, Device - **Answers:** Which processes come to a standstill if an application fails or is replaced? Which processes run without IT support? **Application Portfolio, EAM** LeanIX, Ardoq, Innovator, Sparx EA, Archi - **The system holds:** application landscape, capabilities, target pictures - **In Bpanda:** all layers — imported and exported as ArchiMate® XML - **Answers:** How do I maintain an architecture in two tools without duplicate maintenance? How do processes become part of the architecture roadmap? **ERP, Business Applications, Master Data** SAP, CRM, MDM - **The system holds:** business objects, data objects, products - **In Bpanda:** Business Object, Data Object, Product - **Answers:** Which processes read or write which data? What do the data flows look like, what belongs in the record of processing activities under the GDPR, who is responsible for which master data? **GRC, ISMS, Data Protection, Standards** ISO 9001, ISO 27001 - **The system holds:** requirements, specifications, controls, policies - **In Bpanda:** Requirement, Constraint, Principle, Driver, Assessment - **Answers:** Which processes implement which requirement? Where is there a requirement without a process? What belongs in the audit preparation? **Strategy, Goals, OKR, Capability Maps** - **The system holds:** goals, drivers, capabilities, value streams, measures - **In Bpanda:** Goal, Outcome, Driver, Capability, Value Stream, Course of Action, Value - **Answers:** Which processes contribute to which goal, and which to none? Where is improvement worthwhile first? **Project and Portfolio Management** Jira, Azure DevOps, PPM - **The system holds:** projects, work packages, deliverables, interim states - **In Bpanda:** Work Package, Deliverable, Plateau, Gap, Implementation Event - **Answers:** Which processes does a project change? Who needs to be informed? **Locations, Facilities, Production** Facility Management, MES - **The system holds:** locations, buildings, facilities, devices, material - **In Bpanda:** Location, Facility, Equipment, Device, Material, Distribution Network - **Answers:** Which processes run where and with which facilities? Which are affected by a facility outage? **Contracts, Suppliers, Partners** Contract Management, Supplier Portal - **The system holds:** contracts, external actors, services - **In Bpanda:** Contract, Business Actor, Business Role, Business Service - **Answers:** Which processes depend on which partner or contract? **Document and Quality Management** SharePoint, Confluence, DMS, QMS - **The system holds:** work instructions, forms, templates - **In Bpanda:** Representation, Artifact - **Answers:** Which document belongs to which process, and which is orphaned? You define which element types are active in your Process Space under [Defining Architecture Settings](/en/architecture/architecture-settings); [Linked Architecture Elements and Relationship Types](/en/architecture/manage-linked-architecture-elements) explains what each relationship stands for. ## Embedding Processes in the Architecture [#embedding-processes-in-the-architecture] For every process revision, the architecture automatically contains a **Business Process element**. This is how you embed a process in the architecture: you create a relationship between your element from the external system and this Business Process element. 1. Create or update the element: [createArchitectureElement](/en/api-reference/architecture/architecture-create-architecture-element), [editArchitectureElement](/en/api-reference/architecture/architecture-edit-architecture-element). You transfer an entire inventory with [importArchimateXml](/en/api-reference/architecture/architecture-import-archimate-xml). 2. Retrieve the Business Process element for the process revision: [getArchitectureElementsByRepresentation](/en/api-reference/architecture/architecture-get-architecture-elements-by-representation). 3. Query which relationship types are permitted between the two elements: [findValidReferenceTypesWithDirections](/en/api-reference/architecture/architecture-find-valid-reference-types-with-directions). Only what ArchiMate® allows between the two types is offered. 4. Create the relationship: [addArchitectureElementRelation](/en/api-reference/architecture/architecture-add-architecture-element-relation). If it already exists, the API returns the existing one instead of creating a second. 5. Publish the elements: [publishArchitectureElements](/en/api-reference/architecture/architecture-publish-architecture-elements). Until then they are drafts, just as when created in the user interface. You can read the result back with [findExternalUses](/en/api-reference/architecture/architecture-find-external-uses): all relationships of an element or a process revision, for example every process that uses a particular application. **Note**: The procedure above links elements from other systems **to** a process. The reverse also works: if you create an element of type **Business Process**, a process is implicitly created in Bpanda — without a diagram and without content. You cannot publish this process via the API, because the API does not currently cover the release workflow. A process is released and published as usual in Bpanda, see [Releasing and Publishing Processes](/en/processes/release-process). ## Bpanda as a Source for Other Tools [#bpanda-as-a-source-for-other-tools] In the opposite direction, the API reads whatever other tools need to know about your processes: [process information](/en/api-reference/processes/processes-get-process-info), [versions](/en/api-reference/processes/processes-get-versions), the [diagram as SVG](/en/api-reference/processes/processes-get-svg), the [organizational structure](/en/api-reference/orgstructure/org-structure-get-org-structure), users and groups, and the [architecture reports](/en/api-reference/architecture/architecture-evaluate-report). This lets you embed diagrams in your intranet, show in a portal which applications a process uses, or determine responsible persons automatically. ## Context [#context] The reference under [API](/en/api-reference) describes every operation in full and is generated from the API description — so it always reflects the current state of the system. How architecture elements and their relationships work in Bpanda is described in the [Architecture](/en/architecture) section; who may do what in Bpanda is described in [Roles and Authorizations](/en/getting-started/roles-and-authorizations).