Core - Operators
Module dedicated to platform operators.
The base url for the APIs in this page is at:
/api/admin
A JSON file with OpenAPI data about all core-related admin APIs can be downloaded here.
Get operator
Gets details about a specific operator:
- GET /v1/operators/{id}
Gets details about a specific operator
- Parameters
id (integer) – The id of the operator
- Status Codes
200 OK – Success
- DELETE /v1/operators/{id}
Marks a specific operator as deleted
- Parameters
id (integer) – The id of the operator
- Status Codes
200 OK – Success
Returns a Json positive response and the details of the operator record corresponding to the ID provided:
{
Name: "John", // String
Doe: "Doe", // String
FullName: "John Doe", // String
Roles: ["Admin", "PowerUser"], // String Array
UserName: "JohnDoe", // String
Email: "operator@email.com", // String
MobilePhoneNumber: "071237132132", // String
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
ID: 1234, // Int
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
IsBlocked: false, // Boolean
IsDisabled: false, // Boolean
IsConfirmed: true, // Boolean
IsNotModifiable: false, // Boolean
LastLogonTimestamp: "2001-01-01T01:01:01Z", // DateTime (nullable)
Language: "en-GB", // String
Communities: ["comm1 > comm2",...], // String Array
CommunityIDs: [2, 5, ...], // Int Array
ForcedPasswordChangeRequestDate: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastPasswordChangeTimestamp, "2001-01-01T01:01:01Z", // DateTime
}
Get operator by Guid
Gets details about a specific operator given its guid:
- GET /v1/operators/{id}
Gets details about a specific operator
- Parameters
id (integer) – The id of the operator
- Status Codes
200 OK – Success
- DELETE /v1/operators/{id}
Marks a specific operator as deleted
- Parameters
id (integer) – The id of the operator
- Status Codes
200 OK – Success
Returns a Json positive response and the details of the operator record corresponding to the ID provided:
{
Name: "John", // String
Surname: "Doe", // String
FullName: "John Doe", // String
Roles: ["Admin", "PowerUser"], // String Array
UserName: "JohnDoe", // String
Email: "operator@email.com", // String
MobilePhoneNumber: "071237132132", // String
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
ID: 1234, // Int
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
IsBlocked: false, // Boolean
IsDisabled: false, // Boolean
IsConfirmed: true, // Boolean
IsNotModifiable: false, // Boolean
LastLogonTimestamp: "2001-01-01T01:01:01Z", // DateTime (nullable)
Language: "en-GB", // String
Communities: ["comm1 > comm2",...], // String Array
CommunityIDs: [2, 5, ...], // Int Array
ForcedPasswordChangeRequestDate: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastPasswordChangeTimestamp, "2001-01-01T01:01:01Z", // DateTime
}
Get list of operators
Gets the list of operators (it’s a Paged List APIs, as explained in the introduction):
Returns a list like this:
[
{
"UserName": "Administrator", // String
"CreatedDate": "2019-05-28T11:41:06Z", // DateTime
"Guid": "6b2df906-5636-47c4-8db3-8c215b1333de", // Guid
"AdditionalData": [], // AdditionalData Array
"LastLogonTimestamp": "2020-09-04T10:09:10Z" // DateTime (nullable)
"LCID": 16, // Int
"Language": "it", // String
"IsBlocked": false, // Boolean
"IsConfirmed": true, // Boolean
"IsDisabled": false, // Boolean
"IsNotModifiable": false, // Boolean
"ManualApprovalDate": null, // DateTime (nullable)
"Email": null, // String
"Name": "John", // String
"Surname": "Doe", // String
"FullName": "John Doe", // String
"MobilePhoneNumber": null, // String
"Communities": [Guid Array], // Guid Array
"AdministeredCommunities": [Guid Array], // Guid Array
"Roles": ["Admin",...], // String Array
"ID": 1 // Int
},
...
]
Search operator
Fetches a collection of the active operator records filtered by the name provided:
- GET /v1/operators/search
Fetches a collection of the operators records filtered by [name] otherwise an error will be returned
- Query Parameters
name (string) – A string to look for in any field, even partial
- Status Codes
200 OK – Success
The API expects to receive the search string name in the query parameters.
The request will return the list of all the end user records found:
[
{
ID: 1234, // Int
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
UserName: "UserName", // String
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
AdditionalData:
[
{
ID: 1234, // Int
CreatedDate:"2001-01-01T01:01:01Z", // DateTime
LastUpdated: "2001-01-01T01:01:01Z", // DateTime
FieldName: "Custom Field name", // String
Type: 0, // Int (enum AdditionalValueType)
Value: "abc" // String (nullable)
},
...
],
LastLogonTimestamp: "2001-01-01T01:01:01Z", // DateTime (nullable)
LCID: 1044, // Int
Language: "en-GB", // String
IsBlocked: false, // Boolean
IsConfirmed: true, // Boolean
IsDisabled: false, // Boolean
IsNotModifiable: false, // Boolean
ManualApprovalDate: "2001-01-01T01:01:01Z", // DateTime (nullable)
Email: "user@email.com", // String
Name: "John", // String
Surname: "Doe", // String
FullName: "John Doe", // String
MobilePhoneNumber: "12321321", // String
Communities: ["List","of","community","Guid"], // Guid Array
AdministeredCommunities: [], // Guid Array
Roles: ["EndUser","..."] // String Array
},
...
]
err_NoUserFoundNo active end user found
Add new or edit existing operator record
Persists edits about a new or existing operator:
The body of the request is:
{
ID: 1234, // Int
UserName: "John Doe", // String
Language: "en-GB", // String
Password: "", // String
Email : "", // String
Name: "", // String
Surname: "", // String
IsDisabled: false, // Boolean
MobilePhoneNumber: "", // String
Communities: [1, 2, ...], // Int Array
Roles :["Admin",...] // String Array
}
If the field ID is not provided or it is set to 0, the request will create a new record.
The field Communities represents the IDs of the communities on which the operator can work.
Returns a plain Json positive response if the record has been succesfully added or edited.
err_InvalidElementNo username or role has been provided in the request body, or no operator to edit has been found for the provided ID`
err_DuplicateElementThe request is trying to add a record with the same UserName as an existing one.
err_CannotEditNotModifiableThe request is trying to edit an operator set as not modifiable
err_NoCommunityFoundOne or more of the provided community has not been found. The error code will be followed by a semicolon and the list of the IDs corresponding to the not found communities divided by a comma. I.e.: err_NoCommunityFoud;1,2,3
Delete operator
Mark an operator record as deleted:
- GET /v1/operators/{id}
Gets details about a specific operator
- Parameters
id (integer) – The id of the operator
- Status Codes
200 OK – Success
- DELETE /v1/operators/{id}
Marks a specific operator as deleted
- Parameters
id (integer) – The id of the operator
- Status Codes
200 OK – Success
Returns a plain Json positive response if the request is successful.
Possible errors are:
err_ElementDoesNotExistNo record corresponds to the ID in the request
err_ElementAlreadyDeletedThe record corresponding to the ID has already been deleted
err_CannotDeleteNotModifiableThe request is trying to delete an operator set as not modifiable
Get communities
Gets the list of communities available:
Return a positive Json response and the tree of communities:
[
{
"ID": 12, // Int
"Guid": "9ed1f563-ebc6-4195-9709-feb4daaaf011", // Guid
"Name": "Community 1", // String
"Level": 0, // Int
"Parent": null, // Int (nullable)
"Children": // Community Array
[
{
"ID": 14, // Int
"Guid": "b2686bd5-5fa4-4cca-a904-d616faf86a74", // Guid
"Name": "SubCommunity 1", // String
"Level": 1, // Int
"Parent": null, // Int
"Children": [] // Community Array
},
...
]
},
...
]
Get roles
Gets the list of roles available (specifically intended for the operator users only, not for end-users):
Returns a Json positive response and the list of all the roles:
[
{
Name: "Administrator", // String
Slug: "Admin" // String
},
...
]
Get active session count
Returns the count of the currently active session for the specified operator
- GET /v1/operators/{guid}/active-sessions
Gets the number of active session for the specified user
- Parameters
guid (string) – User guid
- Status Codes
200 OK – Success
If the request is successfull, the API will return a response like this:
{
ActiveSessions: 5, // Int
MaxSessions: 6 // Int
}
where ActiveSessions is the count of the currently active session for the specified operators, while
MaxSessions is the max number of allowed active session, as specified in the configuration variable AUTH_SESSION_LIMIT
configuration variable, or an error if the request is not successful.
Force logoff for a specified operators
Logs off all the currently active session for the specified operator
- POST /v1/operators/force-logoff
Force the logoff of every active session for the specified user
- Status Codes
200 OK – Success
The API expects a body like this:
{
User: '1e4a8a87-9909-4cbb-8452-a8d0872d92a4'
}
where the User field is the guid of the operator that must be forcefully logged off.
The API will return a plain positive error if the request is successfull, a generic error if no User
field is provided, or one of the following errors:
err_NoUserFoundNo operator has ben found for the specified guid
err_NotLoggedInThe specified operator has no currently active session
Force operator to change password during the next login
Requires a password update to be forced on the operator at the next login
- POST /v1/operators/force-password-reset
Force the password reset for the specified operator
- Status Codes
200 OK – Success
The API expects a body like this:
{
User: '1e4a8a87-9909-4cbb-8452-a8d0872d92a4'
}
Where the User field is the GUID of the user who must be forced to change the password.
The API will return a plain positive error if the request is successful, a generic error if no User
field is provided, or one of the following errors:
err_NoUserFoundNo user has ben found for the specified guid
err_PasswordChangeAlreadyRequestedThere are previous request to force password change.