Skip to main content

Organization management

An organization is the issuer or verifier that works inside your ecosystem. Every other Core SDK call takes the organizationId you get when you create one. These methods work the same way in EU Digital Identity, Microsoft Entra, cheqd, Indicio and Polygon.

Create organization​

Creates a new organization in your ecosystem.

import { OpenIdEcosystem } from '@hovi/core-sdk';

const openid = new OpenIdEcosystem({
apiKey: '<YOUR_API_KEY>',
});

const organization = await openid.createOrganization({
name: 'acme-university',
label: 'Acme University',
secret: '<ORGANIZATION_SECRET>',
imageUrl: 'https://example.com/logo.png',
});

Params​

ParameterTypeDescription
namestring (Required)A unique name for the organization.
labelstring (Required)The name holders see, for example in their wallet.
secretstring (Required)The organization secret. You need it to delete the organization. It can't be recovered, so store it safely.
imageUrlstring (Required)A URL of the organization's logo.
webhooksstring[] (Optional)Webhook URLs to add to the organization.
dids{ did, privateKey }[] (Optional)Existing DIDs, with their private keys, for the organization to use.

The response contains the new organizationId, the organization's accessToken, its dids and its webhooks.

note
  • Keep the secret out of your code, for example in an environment variable.

Get all organizations​

Lists the organizations in your ecosystem.

import { OpenIdEcosystem } from '@hovi/core-sdk';

const openid = new OpenIdEcosystem({
apiKey: '<YOUR_API_KEY>',
});

const organizations = await openid.getAllOrganizations();

Params​

ParameterTypeDescription
organizationIdstring (Optional)Return only this organization.

Get organization public DID​

Gets the public DID (decentralized identifier) of an organization. Holders and verifiers use it to check who issued a credential.

import { OpenIdEcosystem } from '@hovi/core-sdk';

const openid = new OpenIdEcosystem({
apiKey: '<YOUR_API_KEY>',
});

const did = await openid.getOrganizationPublicDid({
organizationId: '<ORGANIZATION_ID>',
});

Params​

ParameterTypeDescription
organizationIdstring (Required)Your organization ID.

Rotate organization key​

Replaces the organization's access token with a new one.

import { OpenIdEcosystem } from '@hovi/core-sdk';

const openid = new OpenIdEcosystem({
apiKey: '<YOUR_API_KEY>',
});

const result = await openid.rotateOrganizationKey({
organizationId: '<ORGANIZATION_ID>',
accessToken: '<CURRENT_ACCESS_TOKEN>',
organizationSecret: '<ORGANIZATION_SECRET>',
});

Params​

ParameterTypeDescription
organizationIdstring (Required)Your organization ID.
accessTokenstring (Required)The organization's current access token, returned when you created the organization.
organizationSecretstring (Required)The secret you set when you created the organization.
note
  • The old access token stops working as soon as the rotation succeeds.

Delete organization​

Deletes an organization and all its data.

import { OpenIdEcosystem } from '@hovi/core-sdk';

const openid = new OpenIdEcosystem({
apiKey: '<YOUR_API_KEY>',
});

const result = await openid.deleteOrganization({
organizationId: '<ORGANIZATION_ID>',
organizationSecret: '<ORGANIZATION_SECRET>',
});

Params​

ParameterTypeDescription
organizationIdstring (Required)Your organization ID.
organizationSecretstring (Required)The secret you set when you created the organization.
note
  • This can't be undone. All the organization's data, such as credentials and connections, is deleted too.