Skip to main content

​
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

​
name
string
required
Display name for the organization. Must be between 2 and 200 characters.
​
description
string
required
A short description of the organization. Must be between 2 and 1000 characters.
Logo image encoded as a base64 string or a URL. Defaults to an empty string.
​
website
string
The organization’s website URL.
​
notificationWebhook
string
A fully qualified URL (including protocol and TLD) where the platform sends event notifications. Must include http:// or https://.
​
registrationNumber
string
Official registration number for the organization.
​
countryId
number
Numeric ID for the organization’s country.
​
stateId
number
Numeric ID for the organization’s state or province.
​
cityId
number
Numeric ID for the organization’s city.

​
Response

Returns 201 Created with the created organization object.
​
statusCode
number
HTTP status code. 201 on success.
​
message
string
Human-readable result message.
​
data
object
The newly created organization.
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
  }'

​
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

​
pageNumber
number
default:"1"
Page number to retrieve. Must be 1 or greater.
​
pageSize
number
default:"10"
Number of results per page. Must be between 1 and 100.
​
search
string
Filter organizations by name.
​
role
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>'

​
Get organization

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

​
Path parameters

​
orgId
string
required
UUID of the organization.

​
Response

​
statusCode
number
200 on success.
​
message
string
Human-readable result message.
​
data
object
Organization details.
curl --request GET \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  --header 'Authorization: Bearer <your-jwt-token>'

​
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

​
orgId
string
required
UUID of the organization to update. Must be a valid UUID v4.

​
Request body

​
name
string
Updated display name. Between 2 and 200 characters.
​
description
string
Updated description. Between 2 and 1000 characters.
​
logo
string
Updated logo as a base64-encoded image string. Must pass the ImageBase64Validator check.
​
website
string
Updated website URL.
​
isPublic
boolean
default:"false"
When true, the organization appears in public profile listings.
​
countryId
number
Updated country ID.
​
stateId
number
Updated state or province ID.
​
cityId
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
  }'

​
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

​
orgId
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>'

​
List DIDs

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

​
Path parameters

​
orgId
string
required
UUID of the organization.

​
Response

​
data
object[]
Array of DID records.
curl --request GET \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/dids \
  --header 'Authorization: Bearer <your-jwt-token>'

​
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

​
orgId
string
required
UUID of the organization.

​
Request body

​
did
string
required
The DID string to set as primary (e.g., did:indy:sovrin:staging:ABcDeFGhiJkLmNoPqRsTuV).
​
id
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"
  }'

​
Get org roles

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

​
Path parameters

​
orgId
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>'

​
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

​
orgId
string
required
UUID of the organization.

​
Response

​
data
object
The generated client credentials.
curl --request POST \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/client_credentials \
  --header 'Authorization: Bearer <your-jwt-token>'
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

​
clientId
string
required
The client ID obtained from POST /orgs/:orgId/client_credentials.

​
Request body

​
clientSecret
string
required
The client secret paired with the client ID.

​
Response

​
data
object
The authentication result.
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"
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us