Skip to main content
Organization membership is managed through an email invitation flow. An owner or admin sends an invitation to one or more email addresses. Each invitee receives an email and accepts the invitation through their user account. Once accepted, the user joins the organization with the roles specified in the invitation.

​
Invitation flow

1

Send invitations

An owner or admin calls POST /orgs/:orgId/invitations with a list of email addresses and the desired role IDs for each invitee.
2

Platform sends email

The platform sends an invitation email to each address. The email contains a link directing the user to their CREDEBL account.
3

Invitee views pending invitations

The invitee logs in and calls GET /users/invitations to see all pending invitations across all organizations.
4

Accept or reject

The invitee calls PUT /users/invitations/:invitationId with status: "accepted" or status: "rejected" to act on the invitation.
5

Membership activated

On acceptance, the user becomes a member of the organization with the assigned roles. They can now call GET /orgs/:orgId and other role-gated endpoints.

​
Send invitations

POST /orgs/:orgId/invitations Sends bulk invitations to one or more users. Each entry in the invitations array specifies an email address and one or more role IDs to assign upon acceptance. Required roles: owner, super_admin, admin

​
Path parameters

​
orgId
string
required
UUID of the organization.

​
Request body

​
invitations
object[]
required
Array of invitation objects. Each object targets one email address.
curl --request POST \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/invitations \
  --header 'Authorization: Bearer <your-jwt-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "invitations": [
      {
        "email": "alice@example.com",
        "orgRoleId": ["3c9fce33-ff07-42f9-a573-6f9689809ecf"]
      },
      {
        "email": "bob@example.com",
        "orgRoleId": ["4d0gdf44-ff08-43g0-b684-7g0790810fdg", "3c9fce33-ff07-42f9-a573-6f9689809ecf"]
      }
    ]
  }'
Role IDs (orgRoleId) are UUIDs, not role name strings. Use GET /orgs/:orgId/roles to look up the UUID for each role name.

​
List invitations

GET /orgs/:orgId/invitations Returns all invitations (pending, accepted, or rejected) for an organization. Supports pagination and search. Required roles: owner, super_admin, admin, issuer, verifier, member

​
Path parameters

​
orgId
string
required
UUID of the organization.

​
Query parameters

​
pageNumber
number
default:"1"
Page number to retrieve. Must be 1 or greater.
​
pageSize
number
default:"10"
Number of results per page. Between 1 and 100.
​
search
string
Filter invitations by email address.

​
Response

​
data
object
Paginated invitation list.
curl --request GET \
  --url 'https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/invitations?pageNumber=1&pageSize=10' \
  --header 'Authorization: Bearer <your-jwt-token>'

​
Delete invitation

DELETE /orgs/:orgId/invitations/:invitationId Cancels a pending invitation. Once deleted, the invitation link in the invitee’s email is no longer valid. Required roles: owner, admin

​
Path parameters

​
orgId
string
required
UUID of the organization.
​
invitationId
string
required
UUID of the invitation to cancel. Must be a valid UUID v4.
curl --request DELETE \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/invitations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --header 'Authorization: Bearer <your-jwt-token>'

​
Update user roles

PUT /orgs/:orgId/user-roles/:userId Replaces the existing role assignments for a member of the organization. All previously held roles are replaced by the new orgRoleId list. Required roles: owner, admin

​
Path parameters

​
orgId
string
required
UUID of the organization.
​
userId
string
required
UUID of the user whose roles should be updated. Must be a valid UUID v4.

​
Request body

​
orgRoleId
string[]
required
Non-empty array of role UUIDs to assign to the user. Replaces all existing role assignments for this user in the organization. Retrieve role IDs from GET /orgs/:orgId/roles.
curl --request PUT \
  --url https://your-platform.example.com/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/user-roles/d5e6f7a8-b9c0-1234-defa-bc5678901234 \
  --header 'Authorization: Bearer <your-jwt-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "orgRoleId": [
      "3c9fce33-ff07-42f9-a573-6f9689809ecf",
      "4d0gdf44-ff08-43g0-b684-7g0790810fdg"
    ]
  }'

​
User-side invitation endpoints

The following endpoints are called by the invited user from their own account to view and respond to invitations.

​
List pending invitations

GET /users/invitations Returns all pending invitations for the authenticated user across all organizations. Authentication: JWT bearer token of the invited user.

​
Query parameters

​
pageNumber
number
default:"1"
Page number to retrieve.
​
pageSize
number
default:"10"
Number of results per page. Between 1 and 100.
​
search
string
Filter by organization name.
curl --request GET \
  --url 'https://your-platform.example.com/users/invitations?pageNumber=1&pageSize=10' \
  --header 'Authorization: Bearer <invited-user-jwt-token>'

​
Accept or reject an invitation

PUT /users/invitations/:invitationId Accepts or rejects a specific pending invitation. Once accepted, the user becomes a member of the organization with the assigned roles. Authentication: JWT bearer token of the invited user.

​
Path parameters

​
invitationId
string
required
UUID of the invitation to act on.

​
Request body

​
status
string
required
Set to "accepted" to join the organization or "rejected" to decline. Accepted values: accepted, rejected.
curl --request PUT \
  --url https://your-platform.example.com/users/invitations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --header 'Authorization: Bearer <invited-user-jwt-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "accepted"
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us