Platform Admin Guide
An installation of the Organisation Wallet Suite serves many organisations. One of them, the platform operator organisation, manages the others. The platform admins are the admins of the platform operator organisation who have the platform admin right. In the dashboard they add, suspend and delete organisations, set the features of each organisation and manage the super admins of the organisations.
This guide is for the operators of an on-premise installation. In the service hosted by iGrant.io, iGrant.io is the platform operator.
The platform operator and the platform admins
- An installation has one platform operator organisation. In an installation with the organisation wallet, it is also the wallet provider organisation of the installation.
- Only the command line of the installation makes the platform operator organisation and gives the first platform admin right. No API route sets or removes the platform operator.
- A platform admin manages the organisations, but cannot read the data of another organisation: its credentials, records, keys and settings stay private to that organisation.
- A platform admin manages only the super admins of an organisation. A super admin manages the other admins of the organisation on the page Manage Team.
- The password of a platform admin must have at least 15 characters and at least one special character, for example
!,#or%. A platform admin with a shorter password sets a new password at the next login. Every other new password must have at least 12 characters and at least one special character.
Make the platform operator and the first platform admin
| Installation | How |
|---|---|
| New installation, Helm chart | The last install step, "The platform operator organisation and the first platform admin": the Job api.jobs.bootstrapPlatform makes the organisation, its first admin and the platform admin right in one step. See Install. |
| New installation, Docker Compose | The last installation step: make platform-operator. See the Docker Compose README. |
| An installation upgraded from a release without the platform operator | The Job api.jobs.platformOperator gives the platform operator mark to the wallet provider organisation that exists, and the platform admin right to one of its admins. Do not use bootstrapPlatform for an installation that exists. See The platform operator. |
| No platform admin can log in | An operator of the installation runs igrant-api platform grant-admin --email <admin> in an API pod, for an admin of the platform operator organisation. |
The dashboard
A platform admin sees the menu group Platform below the group Wallet Provider. It has two pages:
- Organisations: all organisations of the installation, with the tiles Organisations, Active, Invited, Suspended and Wallet not deployed. The chips below a name show the status (Invited, Suspended or Deleting), "Wallet not deployed" and "Platform operator".
- Super Admins: the super admins of all organisations and the platform admins.
Manage the organisations
On the page Organisations, each row has a menu with the same entries in the same order.
| Task | Where | What happens |
|---|---|---|
| Add an organisation | The + next to the title, panel "Add Organisation" | Fill in the cards Organisation, First admin, Access and Features. The first admin becomes the super admin of the organisation and gets an invitation by e-mail or a one-time password. An invitation by e-mail needs the e-mail service of the installation; without it, use the one-time password, which the panel shows only once. In an installation with the organisation wallet, the platform deploys the wallet of the new organisation. |
| Read an organisation | Row menu, View Organisation | The status, the time of a suspension, the organisation type, the location, the policy URL, the number of super admins, the features and the wallet unit of the organisation. |
| Deploy the wallet | Row menu, Deploy Wallet Unit | For an organisation with the chip "Wallet not deployed", when the deployment of its wallet failed. |
| Set the features | Row menu, Manage Features | See Organisation features. |
| Send the invitation again | Row menu, Send Invitation Again | Only while the organisation is Invited, that is, before its super admin logs in for the first time. |
| Suspend or resume | Row menu, Suspend Organisation or Resume Organisation | Type the name of the organisation to confirm. The platform operator organisation cannot be suspended. If the dashboard shows a warning that the wallet did not get the new status, select Send again. See Suspension. |
| Delete | Row menu, Delete Organisation | Only a suspended organisation can be deleted, and never the platform operator organisation. Type the name of the organisation to confirm. The deletion cannot be undone. See Deletion. |
Organisation features
An organisation has four features. A platform admin turns them on and off in the panel Manage Features; an organisation cannot change its own features.
| Feature | What it includes | New organisation | Services that it needs |
|---|---|---|---|
| Issuer & Verifier | The issuer, the verifier, the extensions, the verifier files and the sandbox organisations | On | Organisation wallet |
| Wallet Unit (Holder) | The wallet unit of the organisation and the sandbox organisations | Off | Organisation wallet |
| Consent Management | The users, the user requests, the privacy dashboard, the data agreements and the personal data | Off | Consent management |
| Data Marketplace | The data disclosure agreements and the data space, with the data agreements | Off | Consent management and organisation wallet |
Getting Started, Account (the team, the data verifier users and the API keys), Webhooks and Activity Logs are always available and have no switch. The platform operator organisation has all the features of the installation on. The sandbox organisations need Issuer & Verifier or Wallet Unit (Holder).
When a feature is off, the API refuses its routes for that organisation with 403 and the error key feature_disabled, and the dashboard hides its pages.
An installation without consent management or without the wallet
An installation can run without consent management or without the organisation wallet. The Helm chart of the installation decides it: consent.enabled: false or organisationWallet.enabled: false, without an upstream URL of that service (see Services of the installation). A feature is then available only when each service that it needs is installed:
| Installation | Available features |
|---|---|
| Both services (the default) | All four |
| Without consent management | Issuer & Verifier, Wallet Unit (Holder) |
| Without the organisation wallet | Consent Management, without the OID4VC data exchange of a data agreement |
- Manage Features and the card Features of Add Organisation show only the switches of the available features, with a line that names the service that is not installed. The API refuses
truefor another feature with400and the error keyservice_not_installed. - A feature whose service is not installed is off for each organisation, also when its stored value is on. The stored value stays: when the service is installed again, the feature is on again. The count of the features of an organisation ("n of m enabled") counts only the available features.
- The dashboard of each organisation does not show the areas of the service. Each API route of the service answers
404with the error keyservice_not_installed, and the organisations get no webhook event types and no API key scopes of the service. - Without the organisation wallet, a new organisation gets no wallet, and a suspension or a resume sends no state to a wallet.
Suspension
A suspension stops an organisation for a time:
- Within 60 seconds, the API refuses every call with an API key or a login of the organisation and of its sandbox organisations:
401with the error keyorganisation_suspended. - The routes of its organisation wallet answer
403withorganisation_suspended, except the status lists, the issuer metadata and the JWKS. These stay available, so that verifiers can still check the credentials that the organisation issued. - The data, the keys and the wallet units of the organisation stay, and no credential is revoked.
- Resume Organisation returns the organisation to normal work.
Deletion
A deletion ends an organisation and cannot be undone:
- The organisation gets the status Deleting, and it can no longer be suspended, resumed or changed.
- The platform removes its admins, API keys, webhooks and sandbox organisations, and purges its consent data.
- Calls with an API key or a login still get
401withorganisation_suspended. The routes of its organisation wallet answer410withorganisation_deactivated, except the status lists, the issuer metadata and the JWKS, which stay available. - A background job revokes the valid credentials that the organisation issued and its wallet units. Its keys then sign only status list tokens.
- Its wallet data is purged after a grace period of 30 days (7 days for a sandbox organisation).
If the dashboard shows failed steps after a deletion, select Run Deletion Again in the row menu until no failed step is left. The platform does not repeat a failed step by itself.
Manage the super admins and the platform admins
On the page Super Admins, a platform admin can:
- find an account by name or e-mail address, and filter by organisation, by status or by the platform admin right;
- send a password reset by e-mail (Send Password Reset; this needs the e-mail service of the installation);
- set a one-time password (Set One-Time Password): the old password and all sessions end, the panel shows the new password once, and the super admin sets a new password at the next login;
- read the account actions of an account (Account Activity);
- end all sessions of a super admin (End All Sessions);
- disable a super admin (Disable Super Admin, confirmed with the e-mail address) and enable the account again (Enable Super Admin);
- give the platform admin right to an admin of the platform operator organisation (the + of the title, Add Platform Admin, or Give Platform Admin Right), and remove it (Remove Platform Admin Right).
Only an admin of the platform operator organisation can get the platform admin right. To give the right to a new person, first add them as an admin on the page Manage Team of the platform operator organisation.
The API refuses to disable the only active super admin of an organisation, and to disable or remove the last platform admin.
API
The dashboard calls these routes. Each route needs the login of a platform admin; no API key can call them, so no API key can create an organisation. All paths are below /v4/onboard/platform/operator.
| Task | Route |
|---|---|
| Read whether the caller is a platform admin (every admin) | GET /v4/onboard/platform/operator |
| List the organisations, with their status and the numbers of the tiles | GET .../organisations |
| Add an organisation | POST .../organisation |
| Read an organisation | GET .../organisation/{organisationId} |
| Read and set the features | GET, PUT .../organisation/{organisationId}/features |
| Send the invitation again | POST .../organisation/{organisationId}/invitation |
| Suspend or resume | PUT .../organisation/{organisationId}/status |
| Deploy the wallet | POST .../organisation/{organisationId}/wallet |
| Delete, or run the deletion again | DELETE .../organisation/{organisationId} |
| Add an organisation type | POST .../organisation-type |
| List the super admins and the platform admins | GET .../super-admins |
| Send a password reset, set a one-time password, end all sessions | POST .../super-admin/{adminId}/password-reset, .../one-time-password, .../sessions/end |
| Disable or enable a super admin | PUT .../super-admin/{adminId}/status |
| Read the account actions | GET .../super-admin/{adminId}/activity, GET .../admin/{adminId}/activity |
| List the platform admins, and the admins who can get the right | GET .../admins, GET .../admins/candidates |
| Give and remove the platform admin right | POST .../admin, DELETE .../admin/{adminId} |