API methods - users and sessions
Revoke a user’s session
To access this endpoint you must have users.write permission.
DELETE /sessions/{sessionId}
Responses:
Status: 204 - session revoked
Status: 404 - session not found
Get user by ID
To access this endpoint you must have users.read permission.
GET /users/{userId}
Responses:
Status: 200 - user returned
Response body example:
{
"id": "external-idp:e1336ca8-69b2-4ad6-96d1-260a67968b5e",
"externalId": "e1336ca8-69b2-4ad6-96d1-260a67968b5e",
"externalProvider": "external-idp",
"email": "auser@telicent.io",
"active": true,
"preferredName": "A067188",
"createdAt": "2025-11-19T12:23:02.209370",
"lastLogin": "2025-11-21T12:12:44.257464",
"attributes": {
"fullName": "Example User",
"lastName": "Example",
"firstName": "User"
},
"rolesList": [
{
"id": "33118966-7462-4f99-beb5-39943b2e303b",
"name": "USER",
"description": "Standard user of the platform with data access to apps and APIs",
"priority": 100,
"active": true,
"systemRole": false,
"createdAt": "2025-11-19T12:09:26.401003",
"updatedAt": "2025-11-19T12:09:26.401008"
}
],
"permissionsList": [
{
"id": "4477e79e-b368-46fc-9ac8-68cf4af52bdf",
"name": "api.knowledge.read",
"description": "Read from the knowledge dataset ",
"resource": "core",
"action": "read",
"active": true,
"createdAt": "2025-11-19T12:09:26.400427",
"updatedAt": "2025-11-19T12:09:26.400444"
}
],
"groups": [
"admin"
],
"organisationsList": [
{
"id": "0f2d1c8e-5b3a-4c52-9d0b-7a6f2b1e4c93",
"name": "Telicent",
"countryOfRegistration": "GBR"
}
]
}
The organisationsList property contains the organisations the user has been assigned to. It is an empty list if the user has not been assigned to any organisation.
Status: 404 - user not found
Get users
To access this endpoint you must have users.read permission.
GET /users
Responses:
Response body example:
Status: 200 - a summary of all users returned
This endpoint does not provide the same level of detail for users as the Get user by ID endpoint.
{
"count": 1,
"users": [
{
"id": "external-idp:e1336ca8-69b2-4ad6-96d1-260a67968b5e",
"externalId": "e1336ca8-69b2-4ad6-96d1-260a67968b5e",
"externalProvider": "external-idp",
"email": "auser@telicent.io",
"active": true,
"preferredName": "A067188",
"createdAt": "2025-11-19T12:23:02.209370",
"lastLogin": "2025-11-21T12:12:44.257464",
"attributes": {
"fullName": "Example User",
"lastName": "Example",
"firstName": "User"
}
}
]
}
Get user sessions
To access this endpoint you must have users.read permission.
GET /users/{userId}/sessions
Responses:
Status 200: sessions for user returned
Example response body:
{
"count": 1,
"sessions": [
{
"sessionId": "sess_a5221793bcf5437aa158b7ac12dd58ea",
"userId": "external-idp:e1336ca8-69b2-4ad6-96d1-260a67968b5e",
"clientId": "spa-client",
"sessionExpiresAt": "2025-11-21T20:58:48.489905Z",
"scopes": "openid profile offline_access email",
"createdAt": "2025-11-21T12:58:48.489910Z",
"lastAccessedAt": "2025-11-21T12:58:50.187568Z"
}
]
}
Status 404: no sessions found for user
Update user
To access this endpoint you must have users.write permission.
PUT /users/{userId}
This endpoint only requires that you send the top level properties of a user that have changed. The top-level properties are as follows:
activeattributespermissionsrolesgroupsorganisations
For attributes, permissions, roles, groups and organisations it is not sufficient to send only the items to be added. You * *must** send both the new items and the items to be retained, as the values sent will override all existing values for this property in the user’s record.
Request body example (to update a user’s attributes):
{
"attributes": {
"fullName": "Test User",
"lastName": "User",
"firstName": "Test",
"nationality": "GBR"
}
}
Assigning a user to organisations
The organisations property is a list of organisation IDs, as returned by the Organisations API. The list replaces the user’s existing organisations, so to remove a user from all organisations send an empty list.
Request body example (to assign a user to an organisation):
{
"organisations": [
"0f2d1c8e-5b3a-4c52-9d0b-7a6f2b1e4c93"
]
}
Every ID must belong to an existing organisation, otherwise the request is rejected and the user is not changed.
The organisations a user is assigned to determine the permitted_organisations attribute returned for the user. See How organisations affect access for more information.
Responses:
Status: 200 - user updated and returned
Response body example:
{
"id": "external-idp:1608981f-b3a8-4902-a5e3-cadc9c44e587",
"externalId": "1608981f-b3a8-4902-a5e3-cadc9c44e587",
"externalProvider": "external-idp",
"email": "test.user@telicent.io",
"roles": [
"33118966-7462-4f99-beb5-39943b2e303b"
],
"permissions": [
"af29e5e5-6d70-46ce-9bb3-498e2acb8201",
"4477e79e-b368-46fc-9ac8-68cf4af52bdf",
"c8981156-ab41-474e-a456-4c0e6cdac8e5",
"24b84c0b-e79f-432f-bb11-4ed1fbf0ae42",
"1a4238c7-7afc-4034-bc9e-e90b82b90d07",
"b4acbbfc-b34b-4c6e-bd50-64e48153fd54"
],
"groups": [
"admin"
],
"organisations": [
"0f2d1c8e-5b3a-4c52-9d0b-7a6f2b1e4c93"
],
"attributes": {
"fullName": "Test User",
"lastName": "User",
"firstName": "Test",
"nationality": "GBR"
},
"preferredName": "A067194",
"active": true,
"createdAt": "2025-11-19T15:46:51.077941",
"updatedAt": "2025-11-24T16:04:10.361375"
}
Status: 400 - invalid request
Returned, for example, if an organisation ID does not match an existing organisation.
{
"error": "invalid_request",
"error_description": "Attempting to assign user to unknown organisation: 00000000-0000-0000-0000-000000000000"
}
Status: 404 - user not found
Get a user and all the roles and permissions
This endpoint provides a view of the user together with all available roles and permissions. The roles and permissions include an enabledForUser property which is true if the user has been granted the role or permission. This endpoint is designed primarily to provide a complete view for editing purposes.
To access this endpoint you must have users.read permission.
GET /users/{userId}/roles
Responses:
Status: 200 - user, roles and permissions returned
{
"id": "external-idp:1608981f-b3a8-4902-a5e3-cadc9c44e587",
"externalId": "1608981f-b3a8-4902-a5e3-cadc9c44e587",
"externalProvider": "external-idp",
"email": "test.user@telicent.io",
"active": true,
"preferredName": "A067194",
"createdAt": "2025-11-19T15:46:51.077941",
"lastLogin": "2025-11-24T16:04:10.361375",
"attributes": {
"fullName": "Test User",
"lastName": "User",
"firstName": "Test",
"nationality": "GBR"
},
"groupList": [
"admin"
],
"roles": [
{
"id": "33118966-7462-4f99-beb5-39943b2e303b",
"name": "USER",
"description": "Standard user of the platform with data access to apps and APIs",
"priority": 100,
"active": true,
"systemRole": false,
"createdAt": "2025-11-19T12:09:26.401003",
"updatedAt": "2025-11-19T12:09:26.401008",
"permissions": [
{
"id": "1a4238c7-7afc-4034-bc9e-e90b82b90d07",
"name": "api.ontology.read",
"description": "Read from the ontology dataset",
"resource": "core",
"action": "read",
"active": true,
"defaultForRole": true,
"enabledForUser": true
}
],
"enabledForUser": false
}
]
}
Enable a user
To access this endpoint you must have users.write permission.
POST /users/{userId}/enable
Responses:
Status 204: user enabled
Status: 404: user not found
Disable a user
To access this endpoint you must have users.write permission.
POST /users/{userId}/disable
Responses:
Status 204: user disabled
Status: 404: user not found