Create and Validate Organisation

An organisation in Cenda's multi-tenant system is an entity that is configured as an issuer and/or verifier in a Verifiable Credentials (VC) Ecosystem.

The organisation provides a configuration that allows control of the styling in Cenda's pages and certain aspects of how credentials are presented in the wallet. It also creates and maintains the VC configuration needed for the target VC Ecosystem.

Create a New Organisation

Using the Management Portal

Note

The Management Portal stores the DID documents and validates the organisation by itself.

  1. On the Home page, click "Add New Organisation".
  2. Fill out the required fields, as denoted by *.
Note

The Microsoft "linked domain" is only the subdomain if entered through the Management Portal, regardless of whom the domain is managed by. For example, if the complete linked domain that is to be used is "https://documentation.condatis.com" , the linked domain would be "documentation" only. You may use numbers, English characters or hyphens.

Note

The Microsoft "linked domain" must not have already been registered in Microsoft Entra.

  1. Click Submit. You will be redirected to view the details of this new Organisation if the Organisation has been created successfully. The validation is completed in the background. If an error occurs, you will be referred to an error page, which will state the reason for the error where possible.

Using a REST API Client

Create organisation request endpoint
POST /api/Organisation
Create organisation request headers
Header Value
Authorization Bearer access_token
Create organisation request URL parameters

There are no URL parameters needed for this call.

Create organisation request body parameters
Parameter Type Required Description
name string Yes The name of your organisation for ease of identification.
cssUrl string No The styling sheet that determines how the QR code page looks.
roundLogo string No The logo used by wallets that need a round logo (currently none).
squareLogo string Yes The logo used in the MS Authenticator app, appears on the credentials.
primaryColor string Yes The background colour of the credential(s) issued by your organisation.
secondaryColor string Yes The text colour of the credential(s) issued by our organisation.
credentialInstructions string Yes An optional message that can provide information to users who are issued your organisation's credential(s) in the MS Authenticator app.
microsoft.linkedDomain string Yes

(WhenmanagedLinkedDomain is false)		 The URL that shows the organisation domain verified status.
microsoft.managedLinkedDomain boolean Yes A value specifying whether the organisation will be using a Cenda managed linked domain.
microsoft.managedLinkedDomainIdentifier string Yes

(When managedLinkedDomain is true)		 A unique identifier for the organisation using a Cenda managed linked domain. Valid is any alphanumeric value and it can contain hyphens and underscores.

Screenshot highlighting the properties in the MS Authenticator app.

Create organisation request body
POST {{GatewayHubUrl}}/api/organisation
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
  "name": "{{Name}}",
  "cssUrl": "{{cssUrl}}",
  "roundLogo": "{{RoundLogo}}",
  "squareLogo": "{{SquareLogo}}",
  "primaryColor": "{{PrimaryColor}}",
  "secondaryColor": "{{SecondaryColor}}",
  "credentialInstructions": "{{CredentialInstructions}}",
  "microsoft": {
    "linkedDomain": "{{LinkedDomain}}"
  }
}
Create organisation request body (using a Cenda managed linked domain)
POST {{GatewayHubUrl}}/api/organisation
Authorization: Bearer {{accessToken}}
Content-Type: application/json

{
  "name": "{{Name}}",
  "cssUrl": "{{cssUrl}}",
  "roundLogo": "{{RoundLogo}}",
  "squareLogo": "{{SquareLogo}}",
  "primaryColor": "{{PrimaryColor}}",
  "secondaryColor": "{{SecondaryColor}}",
  "credentialInstructions": "{{CredentialInstructions}}",
  "microsoft": {
    "managedLinkedDomain": "{{ManagedLinkedDomainEnabled}}",
    "managedLinkedDomainIdentifier": "{{ManagedLinkedDomainIdentifier}}"
  }
}

The settings {{Name}}, etc will need to be updated as appropriate in the request body, as illustrated in the following examples.

{
  "name": "Condatis",
  "roundLogo": "https://robohash.org/condatis/?set=set4",
  "squareLogo": "https://robohash.org/condatis/?set=set4",
  "primaryColor": "#FFF",
  "secondaryColor": "#000",
  "credentialInstructions": "Please accept this credential to your wallet.",
  "microsoft": {
    "linkedDomain": "https://condatis.com/"
  }
}

{
  "name": "An Organisation",
  "roundLogo": "https://robohash.org/organisation/?set=set4",
  "squareLogo": "https://robohash.org/organisation/?set=set4",
  "primaryColor": "#FFF",
  "secondaryColor": "#000",
  "credentialInstructions": "Please accept this credential to your wallet.",
  "microsoft": {
    "managedLinkedDomain": true,
    "managedLinkedDomainIdentifier": "organisation-identifier"
  }
}
Note

The Microsoft "linkedDomain" must not have already been registered in Microsoft Entra and cannot be a sub-domain.

Create organisation request returns

A successful call will return a 201 Created status code and the created organisation as a JSON file. The call creates an organisationId value, which is required for creating credential templates and clients.

{
  "name": "string",
  "cssUrl": "string",
  "roundLogo": "string",
  "squareLogo": "string",
  "primaryColor": "string",
  "secondaryColor": "string",
  "credentialInstructions": "string",
  "didConfiguration": "string",
  "organisationId": "string",
  "authorityDid": "string",
  "linkedDomainUrl": "string",
  "didDocument": "string",
  "didMethod": "string",
  "validationStatus": "string",
  "issuerDid": "string",
  "createdDate": "string",
  "lastUpdated": "string"
}

Based on the examples above, the JSON objects below show what a successful response looks like with populated values.

Organisation managed linked domain:

{
    "name": "Condatis",
    "roundLogo": "https://robohash.org/condatis/?set=set4",
    "squareLogo": "https://robohash.org/condatis/?set=set4",
    "primaryColor": "#000",
    "secondaryColor": "#FFF",
    "organisationId": "3b3bb21c-6c58-4567-b22b-ddd4013f3d18",
    "authorityDid": "did:web:condatis.com",
    "credentialInstructions": "Please accept the credential to add it to your wallet.",
    "linkedDomainUrl": "https://condatis.com",
    "didMethod": "web",
    "validationStatus": "Not Validated",
    "createdDate": "2024-11-20T14:20:46.3654633Z",
    "didDocument": "{\"id\":\"did:web:condatis.com\",...}",
    "didConfiguration": "{\"@context\":\"https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld\",...}"
}

Cenda managed linked domain:

{
    "name": "An Organisation",
    "roundLogo": "https://robohash.org/organisation/?set=set4",
    "squareLogo": "https://robohash.org/organisation/?set=set4",
    "primaryColor": "#000",
    "secondaryColor": "#FFF",
    "organisationId": "7cbd93ba-1c06-4e95-88cd-7bfce31d2665",
    "authorityDid": "did:web:dids.ccg.condatis.com:organisation-identifier",
    "credentialInstructions": "Please accept the credential to add it to your wallet.",
    "linkedDomainUrl": "https://dids.ccg.condatis.com",
    "didMethod": "web",
    "validationStatus": "Validated",
    "createdDate": "2024-11-20T14:20:46.3654633Z",
    "didDocument": "{\"id\":\"did:web:dids.ccg.condatis.com:organisation-identifier\",...}",
    "didConfiguration": "{\"@context\":\"https://identity.foundation/.well-known/contexts/did-configuration-v0.0.jsonld\",...}"
}

An unsuccessful call will return an error message which should highlight the parameter(s) that needs checking.

{
  "type": "string",
  "title": "string",
  "status": 0,
  "traceId": "string",
  "errors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ]
  },
  "additionalProp1": "string",
  "additionalProp2": "string",
  "additionalProp3": "string"
}

If any values are invalid or missing, an error response will be returned with a message highlighting the area that needs checking.

In this example, the value for the name property is invalid in the body. The error message returned shows that in the errors property.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-d3f24a539b9abb3466fcaf8543ca5001-2aa856a36c27004c-00",
  "errors": {
    "$.name": [
      "The JSON value could not be converted to System.String."
    ]
  }
}

How do I create and validate a new organisation?

The following steps are needed to onboard an organisation, which must be completed before creating credential templates and clients in Cenda.

  1. Create the organisation.
  2. Register Issuer DID configuration (Microsoft Entra Verified ID).
  3. Validate the organisation issuer details (Microsoft Entra Verified ID).

Register Issuer DID configuration

Note

This step is not required for organisations that are using a Cenda managed linked domain.
Cenda will automatically store the DID documents under the managed linked domain as part of the organisation creation process.

If the VC Ecosystem is Microsoft Entra Verified ID the following needs to be done.

Register DID configuration

In order to register the DID configuration the following needs to be done.

  1. Get the "did-configuration" parameter from the create organisation response (or from the GET organisation response).
  2. Unescape the json extracted from the "did-configuration" parameter.
  3. Create a file did-configuration.json and insert the unescaped json.
  4. Upload the file did-configuration.json to the folder ".well-known" in the "linkedDomain".
Register DID document

In order to register the DID document the following needs to be done.

  1. Get the "did-document" parameter from the create organisation response (or from the GET organisation response).
  2. Unescape the json extracted from the "did-document" parameter.
  3. Create a file did-document.json and insert the unescaped json.
  4. Upload the file did-document.json to the folder ".well-known" in the "linkedDomain".

Validate the organisation issuer details

Note

This step is not required for organisations that are using a Cenda managed linked domain.
Cenda will automatically validate the issuer as part of the organisation creation process.

If the VC Ecosystem is Microsoft Entra Verified ID the issuer needs to be validated as per Microsoft Admin API Documentation.

This is done in Cenda by calling the validate organisation endpoint.

Validate organisation endpoint
POST {{GatewayHubUrl}}/api/organisation/{{OrganisationId}}/validate
Authorization: Bearer {{accessToken}}
Content-Type: application/json

The response from this call will be a 200 OK with body text “Validated” or “Not Validated”.

Validation status in GET organisation endpoint

The validation status of an organisation can also be ascertained by calling the GET organisation endpoint, the response of which includes the validation status:

{ 
: 
  "didMethod": "web",  
  "validationStatus": "Validated", 
: 
} 
'''

Enable FaceCheck for an organisation

Note

This step is only required for an organisation that want to perform a Face Check during verification.

If the VC Ecosystem is Microsoft Entra Verified ID the verifier needs to have Face Check enabled.

This is done in Cenda by calling the enable FaceCheck organisation endpoint.

Enable FaceCheck organisation endpoint
POST {{GatewayHubUrl}}/api/v2/organisation/{{OrganisationId}}/enablefacecheck
Authorization: Bearer {{accessToken}}
Content-Type: application/json

The response from this call will be a 200 OK when successful. If the call is not successful the response will be as per the endpoint definition in the Swagger documentation.