Manage organizations

Create organization

POST /orgs Creates a new organization. The authenticated user becomes the owner of the new organization. Required roles: Authenticated user (no org role required — creates a new org).

Request body

string

required

Display name for the organization. Must be between 2 and 200 characters.

string

required

A short description of the organization. Must be between 2 and 1000 characters.

string

Logo image encoded as a base64 string or a URL. Defaults to an empty string.

string

The organization’s website URL.

string

A fully qualified URL (including protocol and TLD) where the platform sends event notifications. Must include http:// or https://.

string

Official registration number for the organization.

number

Numeric ID for the organization’s country.

number

Numeric ID for the organization’s state or province.

number

Numeric ID for the organization’s city.

Response

Returns 201 Created with the created organization object.

number

HTTP status code. 201 on success.

string

Human-readable result message.

object

The newly created organization.

Show properties

string

UUID of the created organization.

string

Organization name.

string

Organization description.

string

URL or base64-encoded logo.

string

Organization website.

string

Registration number.

boolean

Whether the organization is publicly listed.

string

ISO 8601 timestamp of creation.

string

ISO 8601 timestamp of last update.

curl --request POST \
  --url https://your-platform.example.com/orgs \
  --header 'Authorization: Bearer <your-jwt-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Acme Corp",
    "description": "A credential-issuing organization for Acme Corp.",
    "website": "https://acme.example.com",
    "notificationWebhook": "https://acme.example.com/webhooks/credebl",
    "countryId": 101,
    "stateId": 4008,
    "cityId": 1000
  }'

{
  "statusCode": 201,
  "message": "Organization created successfully",
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Acme Corp",
    "description": "A credential-issuing organization for Acme Corp.",
    "logoUrl": "",
    "website": "https://acme.example.com",
    "isPublic": false,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

List organizations

GET /orgs Returns all organizations the authenticated user is a member of. Supports filtering by role and pagination. Required roles: Authenticated user.

Query parameters

number

default:"1"

Page number to retrieve. Must be 1 or greater.

number

default:"10"

Number of results per page. Must be between 1 and 100.

string

Filter organizations by name.

string

Filter by the user’s role within each organization. Accepted values: owner, admin, issuer, verifier, member, holder, super_admin, platform_admin.

curl --request GET \
  --url 'https://your-platform.example.com/orgs?pageNumber=1&pageSize=10&role=owner' \
  --header 'Authorization: Bearer <your-jwt-token>'

{
  "statusCode": 200,
  "message": "Organizations fetched successfully",
  "data": {
    "totalItems": 2,
    "hasNextPage": false,
    "hasPreviousPage": false,
    "nextPage": null,
    "previousPage": null,
    "lastPage": 1,
    "data": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Acme Corp",
        "description": "A credential-issuing organization.",
        "logoUrl": "",
        "isPublic": false,
        "userOrgRoles": [{ "orgRole": { "name": "owner" } }]
      }
    ]
  }
}

Get organization

GET /orgs/:orgId Returns the details of a single organization by its ID. Required roles: owner, admin, issuer, verifier, member

Path parameters

string

required

UUID of the organization.

Response

number

200 on success.

string

Human-readable result message.

object

Organization details.

Show properties

string

UUID of the organization.

string

Organization name.

string

Organization description.

string

URL or base64-encoded logo.

string

Organization website.

boolean

Whether the organization has a public profile.

string

Official registration number.

number

Country identifier.

number

State or province identifier.

number

City identifier.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

curl --request GET \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  --header 'Authorization: Bearer <your-jwt-token>'

{
  "statusCode": 200,
  "message": "Organization fetched successfully",
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Acme Corp",
    "description": "A credential-issuing organization.",
    "logoUrl": "",
    "website": "https://acme.example.com",
    "isPublic": false,
    "registrationNumber": "ACM-2024-001",
    "countryId": 101,
    "stateId": 4008,
    "cityId": 1000,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Update organization

PUT /orgs/:orgId Updates the mutable fields of an existing organization. All body fields are optional — only the fields you include are changed. Required roles: owner, admin

Path parameters

string

required

UUID of the organization to update. Must be a valid UUID v4.

Request body

string

Updated display name. Between 2 and 200 characters.

string

Updated description. Between 2 and 1000 characters.

string

Updated logo as a base64-encoded image string. Must pass the ImageBase64Validator check.

string

Updated website URL.

boolean

default:"false"

When true, the organization appears in public profile listings.

number

Updated country ID.

number

Updated state or province ID.

number

Updated city ID.

curl --request PUT \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  --header 'Authorization: Bearer <your-jwt-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "Updated description for Acme Corp.",
    "website": "https://new.acme.example.com",
    "isPublic": true
  }'

{
  "statusCode": 200,
  "message": "Organization updated successfully"
}

Delete organization

DELETE /orgs/:orgId Permanently deletes an organization and all associated data. This action is irreversible. Required roles: owner

Deleting an organization removes all associated schemas, credentials, and DID configurations. This cannot be undone.

Path parameters

string

required

UUID of the organization to delete. Must be a valid UUID v4.

curl --request DELETE \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  --header 'Authorization: Bearer <your-jwt-token>'

{
  "statusCode": 200,
  "message": "Organization deleted successfully"
}

List DIDs

GET /orgs/:orgId/dids Returns all decentralized identifiers (DIDs) registered to an organization. Required roles: owner, admin, issuer, member

Path parameters

string

required

UUID of the organization.

Response

object[]

Array of DID records.

Show DID object properties

string

UUID of the DID record.

string

The DID string (e.g., did:indy:sovrin:abc123).

boolean

Whether this is the organization’s primary DID.

string

ISO 8601 creation timestamp.

curl --request GET \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/dids \
  --header 'Authorization: Bearer <your-jwt-token>'

{
  "statusCode": 200,
  "message": "Organization DIDs fetched successfully",
  "data": [
    {
      "id": "7e5d8a1b-3c2e-4f6a-9b0d-1e2f3a4b5c6d",
      "did": "did:indy:sovrin:staging:ABcDeFGhiJkLmNoPqRsTuV",
      "isPrimaryDid": true,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Set primary DID

PUT /orgs/:orgId/primary-did Designates one of the organization’s registered DIDs as its primary identifier. The primary DID is used by default in credential issuance and verification flows. Required roles: owner, admin, issuer, verifier, member

Path parameters

string

required

UUID of the organization.

Request body

string

required

The DID string to set as primary (e.g., did:indy:sovrin:staging:ABcDeFGhiJkLmNoPqRsTuV).

string

required

The UUID of the DID record in the platform database. Retrieve this from GET /orgs/:orgId/dids.

curl --request PUT \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/primary-did \
  --header 'Authorization: Bearer <your-jwt-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "did": "did:indy:sovrin:staging:ABcDeFGhiJkLmNoPqRsTuV",
    "id": "7e5d8a1b-3c2e-4f6a-9b0d-1e2f3a4b5c6d"
  }'

{
  "statusCode": 201,
  "message": "Primary DID set successfully"
}

Get org roles

GET /orgs/:orgId/roles Returns the available role definitions for a specific organization. Required roles: owner, admin

Path parameters

string

required

UUID of the organization.

curl --request GET \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/roles \
  --header 'Authorization: Bearer <your-jwt-token>'

{
  "statusCode": 200,
  "message": "Organization roles fetched successfully",
  "data": [
    { "id": "1a7eac11-ff05-40d7-8351-4d7467687cad", "name": "owner" },
    { "id": "2b8fbd22-ff06-41e8-9462-5e8578798dbe", "name": "admin" },
    { "id": "3c9fce33-ff07-42f9-a573-6f9689809ecf", "name": "issuer" },
    { "id": "4d0gdf44-ff08-43g0-b684-7g0790810fdg", "name": "verifier" },
    { "id": "5e1heg55-ff09-44h1-c795-8h1801921geh", "name": "member" }
  ]
}

Generate client credentials

POST /orgs/:orgId/client_credentials Creates a client ID and client secret for the organization, enabling machine-to-machine (M2M) access without a user session. Use the returned credentials with POST /orgs/:clientId/token to obtain an access token. Required roles: owner

Path parameters

string

required

UUID of the organization.

Response

object

The generated client credentials.

Show properties

string

The client identifier. Use this as the :clientId path parameter when requesting a token.

string

The client secret. Store this securely — it is not retrievable after this response.

curl --request POST \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/client_credentials \
  --header 'Authorization: Bearer <your-jwt-token>'

{
  "statusCode": 201,
  "message": "Organization client credentials created successfully",
  "data": {
    "clientId": "acme-corp-client-abc123",
    "clientSecret": "s3cr3t-v4lue-abc123xyz"
  }
}

The clientSecret is returned only once. Copy it immediately and store it in a secure secrets manager.

Get client token

POST /orgs/:clientId/token Exchanges an organization’s client credentials for an access token using the client_credentials OAuth 2.0 grant. The token is returned in the response body and a session_id cookie is also set. Authentication: No JWT bearer token required. Uses client credentials in the request body.

Path parameters

string

required

The client ID obtained from POST /orgs/:orgId/client_credentials.

Request body

string

required

The client secret paired with the client ID.

Response

object

The authentication result.

Show properties

string

A bearer token to use in subsequent API requests via Authorization: Bearer.

string

Session identifier also set as an httpOnly cookie named session_id.

number

Token lifetime in seconds.

curl --request POST \
  --url https://your-platform.example.com/orgs/acme-corp-client-abc123/token \
  --header 'Content-Type: application/json' \
  --data '{
    "clientSecret": "s3cr3t-v4lue-abc123xyz"
  }'

{
  "statusCode": 200,
  "message": "Client credentials authenticated successfully",
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "sessionId": "sess_abc123xyz",
    "expiresIn": 3600
  }
}

Authentication

Organizations

Connections & Credentials

Ecosystem & Wallet

Create organization

Request body

Response

List organizations

Query parameters

Get organization

Path parameters

Response

Update organization

Path parameters

Request body

Delete organization

Path parameters

List DIDs

Path parameters

Response

Set primary DID

Path parameters

Request body

Get org roles

Path parameters

Generate client credentials

Path parameters

Response

Get client token

Path parameters

Request body

Response

​Create organization

​Request body

​Response

​List organizations

​Query parameters

​Get organization

​Path parameters

​Response

​Update organization

​Path parameters

​Request body

​Delete organization

​Path parameters

​List DIDs

​Path parameters

​Response

​Set primary DID

​Path parameters

​Request body

​Get org roles

​Path parameters

​Generate client credentials

​Path parameters

​Response

​Get client token

​Path parameters

​Request body

​Response

Create organization

Request body

Response

List organizations

Query parameters

Get organization

Path parameters

Response

Update organization

Path parameters

Request body

Delete organization

Path parameters

List DIDs

Path parameters

Response

Set primary DID

Path parameters

Request body

Get org roles

Path parameters

Generate client credentials

Path parameters

Response

Get client token

Path parameters

Request body

Response