roles

Version 0.1.08 operations

Predefined and custom roles with their permissions

GET/organisations/{id}/rolesDashboard session

Parameters

idstringpathrequired

Responses

200
- idstring (uuid)required
- keystring | nullrequired
  Predefined role key, null for custom
- namestringrequired
- descriptionstring | nullrequired
- predefinedbooleanrequired
- permissionsstring[]required
- memberCountnumberrequired
  Members of this organisation holding the role

Code samples

curl -X GET "$KONNECT_API_URL/organisations/id/roles" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

[
  {
    "id": "id",
    "key": "key",
    "name": "name",
    "description": "description",
    "predefined": true,
    "permissions": [
      "payments.view"
    ],
    "memberCount": 1
  }
]

Create a custom role, or duplicate one with basedOnRoleId

POST/organisations/{id}/rolesDashboard session

Parameters

idstringpathrequired

Request body application/json

namestringrequired
descriptionstring
permissionsstring[]
Required unless basedOnRoleId is given
basedOnRoleIdstring (uuid)
Duplicate the permissions of this role

Responses

201
- idstring (uuid)required
- keystring | nullrequired
  Predefined role key, null for custom
- namestringrequired
- descriptionstring | nullrequired
- predefinedbooleanrequired
- permissionsstring[]required
- memberCountnumberrequired
  Members of this organisation holding the role

Code samples

curl -X POST "$KONNECT_API_URL/organisations/id/roles" \
  -H "Cookie: konnect_session=$KONNECT_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Statistics only",
  "description": "description",
  "permissions": [
    "payments.view"
  ],
  "basedOnRoleId": "basedOnRoleId"
}'

Example: request body

{
  "name": "Statistics only",
  "description": "description",
  "permissions": [
    "payments.view"
  ],
  "basedOnRoleId": "basedOnRoleId"
}

Example: 201

{
  "id": "id",
  "key": "key",
  "name": "name",
  "description": "description",
  "predefined": true,
  "permissions": [
    "payments.view"
  ],
  "memberCount": 1
}

Edit a custom role (predefined roles are fixed)

PATCH/organisations/{id}/roles/{roleId}Dashboard session

Parameters

idstringpathrequired
roleIdstringpathrequired

Request body application/json

namestring
descriptionstring
permissionsstring[]

Responses

200
- idstring (uuid)required
- keystring | nullrequired
  Predefined role key, null for custom
- namestringrequired
- descriptionstring | nullrequired
- predefinedbooleanrequired
- permissionsstring[]required
- memberCountnumberrequired
  Members of this organisation holding the role

Code samples

curl -X PATCH "$KONNECT_API_URL/organisations/id/roles/roleId" \
  -H "Cookie: konnect_session=$KONNECT_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "name",
  "description": "description",
  "permissions": [
    "payments.view"
  ]
}'

Example: request body

{
  "name": "name",
  "description": "description",
  "permissions": [
    "payments.view"
  ]
}

Example: 200

{
  "id": "id",
  "key": "key",
  "name": "name",
  "description": "description",
  "predefined": true,
  "permissions": [
    "payments.view"
  ],
  "memberCount": 1
}

Delete a custom role that no member or pending invitation uses

DELETE/organisations/{id}/roles/{roleId}Dashboard session

Parameters

idstringpathrequired
roleIdstringpathrequired

Responses

Code samples

curl -X DELETE "$KONNECT_API_URL/organisations/id/roles/roleId" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

The pending ownership transfer, if any

GET/organisations/{id}/ownership-transferDashboard session

Parameters

idstringpathrequired

Responses

200
- idstring (uuid)required
- organisationIdstring (uuid)required
- fromUserIdstring (uuid)required
- toUserIdstring (uuid)required
- statusstringrequired
  - enum: "pending", "accepted", "cancelled"
- expiresAtstring (date-time)required
- decidedAtstring (date-time) | nullrequired
- createdAtstring (date-time)required

Code samples

curl -X GET "$KONNECT_API_URL/organisations/id/ownership-transfer" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

{
  "id": "id",
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "fromUserId": "fromUserId",
  "toUserId": "toUserId",
  "status": "pending",
  "expiresAt": "2026-10-01T09:30:00.000Z",
  "decidedAt": "2026-10-01T09:30:00.000Z",
  "createdAt": "2026-10-01T09:30:00.000Z"
}

Owner only: offer ownership to a member (requires re-authentication)

POST/organisations/{id}/ownership-transferDashboard session

Parameters

idstringpathrequired

Request body application/json

toUserIdstring (uuid)required
A current member of the organisation

Responses

201
- idstring (uuid)required
- organisationIdstring (uuid)required
- fromUserIdstring (uuid)required
- toUserIdstring (uuid)required
- statusstringrequired
  - enum: "pending", "accepted", "cancelled"
- expiresAtstring (date-time)required
- decidedAtstring (date-time) | nullrequired
- createdAtstring (date-time)required

Code samples

curl -X POST "$KONNECT_API_URL/organisations/id/ownership-transfer" \
  -H "Cookie: konnect_session=$KONNECT_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "toUserId": "toUserId"
}'

Example: request body

{
  "toUserId": "toUserId"
}

Example: 201

{
  "id": "id",
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "fromUserId": "fromUserId",
  "toUserId": "toUserId",
  "status": "pending",
  "expiresAt": "2026-10-01T09:30:00.000Z",
  "decidedAt": "2026-10-01T09:30:00.000Z",
  "createdAt": "2026-10-01T09:30:00.000Z"
}

The new owner accepts; the former owner becomes Administrator

POST/organisations/{id}/ownership-transfer/{transferId}/acceptDashboard session

Parameters

idstringpathrequired
transferIdstringpathrequired

Responses

200
- idstring (uuid)required
- organisationIdstring (uuid)required
- fromUserIdstring (uuid)required
- toUserIdstring (uuid)required
- statusstringrequired
  - enum: "pending", "accepted", "cancelled"
- expiresAtstring (date-time)required
- decidedAtstring (date-time) | nullrequired
- createdAtstring (date-time)required

Code samples

curl -X POST "$KONNECT_API_URL/organisations/id/ownership-transfer/transferId/accept" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

{
  "id": "id",
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "fromUserId": "fromUserId",
  "toUserId": "toUserId",
  "status": "pending",
  "expiresAt": "2026-10-01T09:30:00.000Z",
  "decidedAt": "2026-10-01T09:30:00.000Z",
  "createdAt": "2026-10-01T09:30:00.000Z"
}

The owner withdraws, or the recipient declines, a pending transfer

DELETE/organisations/{id}/ownership-transfer/{transferId}Dashboard session

Parameters

idstringpathrequired
transferIdstringpathrequired

Responses

200
- idstring (uuid)required
- organisationIdstring (uuid)required
- fromUserIdstring (uuid)required
- toUserIdstring (uuid)required
- statusstringrequired
  - enum: "pending", "accepted", "cancelled"
- expiresAtstring (date-time)required
- decidedAtstring (date-time) | nullrequired
- createdAtstring (date-time)required

Code samples

curl -X DELETE "$KONNECT_API_URL/organisations/id/ownership-transfer/transferId" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

{
  "id": "id",
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "fromUserId": "fromUserId",
  "toUserId": "toUserId",
  "status": "pending",
  "expiresAt": "2026-10-01T09:30:00.000Z",
  "decidedAt": "2026-10-01T09:30:00.000Z",
  "createdAt": "2026-10-01T09:30:00.000Z"
}