Organization Management

Organization management allows you to create, retrieve, manage, and delete organizations across multiple ecosystems (OpenID, Polygon, Indicio, Cheqd). Organizations serve as isolated environments for self sovereign identity identity operations within each ecosystem. This section covers methods to handle organization lifecycle and configuration, including webhooks and key rotation.

• Create Organization
• Get All Organizations
• Get Organization Public DID
• Rotate Organization Key
• Delete Organization

Create Organization

Creates a new organization in the specified ecosystem.

import { OpenIDEcosystem } from '@openid/core-sdk';

const openid = new OpenIDEcosystem({
  apiKey: 'your-ecosystem-api-key',
});

const organization = await openid.createOrganization({
  organizationName: 'your-organization-name',
  organizationLabel: 'Your Organization Label',
  organizationSecret: 'secret1243',
  imageUrl: 'https://example.com/logo.png',
});

Params

Parameter	Type	Description
organizationName	string (Required)	A unique name for the organization.
organizationLabel	string (Required)	A human-readable label for the organization.
organizationSecret	string (Required)	A secret key for organization access (keep secure).
imageUrl	string (Required)	A URL pointing to the organization's logo or image.
webhooks	string[] (Optional)	An array of webhook URLs for organization notifications.

note

• Ensure the organizationName is unique within the respective ecosystem.
• Store organizationSecret securely (e.g., in environment variables) to prevent exposure.

Get All Organizations

Retrieves a list of all organizations associated with the authenticated API key in the specified ecosystem.

import { OpenIDEcosystem } from '@openid/core-sdk';

const openid = new OpenIDEcosystem({
  apiKey: 'your-ecosystem-api-key',
});

const organizations = await openid.getAllOrganizations({});

Params

Parameter	Type	Description
organizationId	string (Optional)	Filter by a specific organization ID (if omitted, returns all organizations).

note

• Use the organizationId filter for pagination or specific organization queries if managing multiple organizations.
• Response size may vary; consider limiting with additional query parameters (if supported in future updates).

Get Organization Public DID

Retrieves the public DID (Decentralized Identifier) for a specified organization in the respective ecosystem.

import { OpenIDEcosystem } from '@openid/core-sdk';

const openid = new OpenIDEcosystem({
  apiKey: 'your-ecosystem-api-key',
});

const did = await openid.getOrganizationPublicDid({
  organizationId: 'your-organization-id',
});

Params

Parameter	Type	Description
organizationId	string (Required)	The ID of the organization to query.

note

• The public DID is used for identity verification and should be shared only with trusted parties.
• Ensure the organizationId exists, or the method will return an error.

Rotate Organization Key

Rotates the access token for a organization in the specified ecosystem, enhancing security by generating a new key.

import { OpenIDEcosystem } from '@openid/core-sdk';

const openid = new OpenIDEcosystem({
  apiKey: 'your-ecosystem-api-key',
});

const newToken = await openid.rotateOrganizationKey({
  organizationId: 'your-organization-id',
  accessToken: 'current-token-xyz',
  organizationSecret: 'your-organization-secret',
});

Params

Parameter	Type	Description
organizationId	string (Required)	The ID of the organization to rotate.
accessToken	string (Required)	The current access token for authentication.
organizationSecret	string (Required)	The organization's secret key for validation.

note

• Rotate keys periodically or after a security breach.
• The old accessToken becomes invalid immediately after a successful rotation.

Delete Organization

Deletes a organization and all associated data from the specified ecosystem.

import { OpenIDEcosystem } from '@openid/core-sdk';

const openid = new OpenIDEcosystem({
  apiKey: 'your-ecosystem-api-key',
});

const result = await openid.deleteOrganization({
  organizationId: 'your-organization-id',
  organizationSecret: 'your-organization-secret',
});

Params

Parameter	Type	Description
organizationId	string (Required)	The ID of the organization to delete.
organizationSecret	string (Required)	The organization's secret key for validation.

note

• This action is irreversible and deletes all organization data (credentials, connections, etc).
• Verify the organizationId and organizationSecret before proceeding to avoid accidental deletion.