Organisations

Add organisation

POST/v4/onboard/platform/operator/organisation

Adds an organisation to the installation, with its first admin and its organisation wallet. The first admin becomes the super admin of the organisation and gets access by an invitation e-mail or a one-time password (access). A new organisation has only the feature Issuer & Verifier on; configuredFeatures sets the features that differ.

The call has three steps: the organisation and its first admin, then the deployment of its wallet, then the access of the first admin. A failure of the wallet deployment or of the access does not undo the organisation: the answer is still 201, with walletDeployment.status failed, or without oneTimePassword. Then deploy the wallet with Deploy organisation wallet, send the invitation again, or set a one-time password. An answer with a one-time password has Cache-Control: no-store.

Add organisation

Language of the request sample

curl -X POST 'https://demo-api.igrant.io/v4/onboard/platform/operator/organisation' \
  -H 'Authorization: Bearer <access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "organisation": {
    "name": "Acme Bank",
    "location": "Stockholm, Sweden",
    "typeId": "64e0c1a2b3c4d5e6f7a8b9c0",
    "policyUrl": "https://acme-bank.example.com/privacy",
    "description": "Retail bank that issues and verifies payment credentials."
  },
  "firstAdmin": {
    "email": "[email protected]",
    "name": "Jane Doe"
  },
  "access": "oneTimePassword",
  "configuredFeatures": {
    "walletUnit": true
  }
}'

{
  "organisation": {
    "id": "6731f0c2a1b2c3d4e5f60789",
    "name": "Acme Bank",
    "location": "Stockholm, Sweden",
    "type": {
      "id": "64e0c1a2b3c4d5e6f7a8b9c0",
      "type": "Banking"
    },
    "policyUrl": "https://acme-bank.example.com/privacy",
    "status": "invited",
    "isPlatformOperator": false,
    "superAdminCount": 1,
    "createdAt": "2026-11-12T10:00:00Z",
    "suspendedAt": null,
    "wallet": {
      "deploymentStatus": "deployed",
      "walletOrganisationId": "2f6c1d0e-8b7a-4c3d-9e1f-0a2b3c4d5e6f",
      "isWalletProvider": false
    },
    "features": {
      "enabled": 2,
      "total": 4
    }
  },
  "firstAdmin": {
    "id": "6731f1d8a1b2c3d4e5f6078a",
    "email": "[email protected]",
    "name": "Jane Doe",
    "roleName": "SuperAdmin",
    "organisation": {
      "id": "6731f0c2a1b2c3d4e5f60789",
      "name": "Acme Bank"
    },
    "status": "passwordChangeRequired",
    "lastSignIn": null,
    "platformAdmin": null
  },
  "oneTimePassword": {
    "oneTimePassword": "Xq7#mP2v!kR9wT4z",
    "expiresAt": "2026-11-19T10:00:00Z"
  },
  "walletDeployment": {
    "status": "deployed"
  }
}

Authorizations

Authorizationstringheaderrequired
An access token: Bearer <access-token>.

Body

application/json

organisationobjectrequired
firstAdminobjectrequired
accessenum<string>required
How the first admin gets access. invitation: an invitation e-mail; this needs the e-mail service of the installation. oneTimePassword: a one-time password in the answer, which you give to the admin.
Available options:invitation,oneTimePassword
Example:"oneTimePassword"
configuredFeaturesobject
The features that differ from those of a new organisation. A missing member keeps the value of a new organisation. A removed feature of an earlier release (for example webhooks or privacyDashboard) gets 400.

Response

application/json

The organisation is made.

organisationobject
An organisation of the installation as a platform admin sees it: its profile and its state. It has no data of the organisation, such as its credentials, records or keys.
firstAdminobject
An admin account as a platform admin sees it.
oneTimePasswordobject
A one-time password. The value is in this answer only: give it to the admin in a safe way. The answer has Cache-Control: no-store.
walletDeploymentobject
The result of the deployment of the organisation wallet.