User Management (GraphQL)
To update users' data, Starmind offers a GraphQL API. This API can be used to create, update, deactivate, restore or delete users.
Each request requires an access token, that authenticates the requester. Information about authentication can be found here: REST-API Authentication.
base_domain is the base URL of your application (format: customer.starmind.com)
User Attributes
Parameter | Type | Nullable | Required for creation | Description |
---|---|---|---|---|
string | ✗ | ✓ | max. 191 characters. | |
firstname | string | ✗ | ✓ | max. 50 characters. |
lastname | string | ✗ | ✓ | max. 50 characters. |
externalId | string | ✗ | ✗ | max. 250 characters. Must be an unique identifier. |
languageId | languageId (language code) | ✗ | ✗ | The interface language for the user. |
location | string | ✓ | ✗ | Location-specific information (department, etc.). Max. 100 characters. |
about | text | ✓ | ✗ | Text to describe the user. This information is showed in the user profile. Max. 100 characters. |
countryId | string | ✓ | ✗ | Country code in ISO 3166-2 format like ch, de, us. |
company | text | ✓ | ✗ | Company of the user. Max. 255 characters. |
department | text | ✓ | ✗ | Department of the user. Max. 255 characters. |
position | text | ✓ | ✗ | Position of the user. Max. 255 characters. |
employmentStart | datetime | ✓ | ✗ | The employment start date of the user in the format yyyy-mm-dd. |
Search User
Replace the search term with e.g. the email address of the user or their externalId.
*inputs:
searchText(required): set as "" to search for all users
offset (Optional): default value is 0
limit (Optional): default value is 100*
Header
Content-Type: application/json
Authorization: Bearer {{access_token}}
Body
{
"query":"query getUsers($searchText: String, $offset: Offset, $limit: Limit) {
users(searchText: $searchText, offset: $offset, limit:$limit){
globalUserId,
externalId,
firstname,
lastname,
email,
location,
department,
position,
gender,
about,
languageId,
employmentStart,
isSystem,
isHidden,
avatarUrl,
dateDeleted
}
}",
"variables":{
"searchText":"{search_term}",
"offset":"{offset}",
"limit":"{limit}"
}
}
Update User
Only send the attributes which should be changed. The list of the attributes needs only be adjusted in the query. Please note that the attribute "globalUserId" is mandatory, as it is how the system will identify the user to update.
POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1
Header
Content-Type: application/json
Authorization: Bearer {{access_token}}
Body
{
"query":"mutation updateUser($updateUserInput: UpdateUserInput!) {updateUser(input: $updateUserInput) {firstname, lastname, email, externalId, languageId, countryId, gender,company,department,position,location, about, globalUserId}",
"variables":{
"updateUserInput":{
"firstname":"{{first_name}}",
"lastname":"{{last_name}}",
"externalId":"{{externalId}}",
"languageId":"{{language_id}}",
"location":"{{location}}",
"company":"{{company}}",
"position":"{{position}}",
"department":"{{department}}",
"countryId":"{{country_id}}",
"about":"{{User description}}",
"globalUserId":"{{globalUserId}}"
}
}
}
If the email address should be updated the following request should be used:
POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1
Header
Content-Type: application/json
Authorization: Bearer {{access_token}}
Body
{
"query": "mutation updatePrivilegedUserAndEmail( $updateUserEmailInput: UpdateUserEmailInput!) {updateUserEmail(input: $updateUserEmailInput) {globalUserId, email}}",
"variables": {
"updateUserEmailInput": {
"email": "{email}",
"globalUserId": "{global-user-id}"
}
}
}
Deactivating User
Replace the {{user_id}} with the id of the user which should be deactivated.
POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1
Header
Content-Type: application/json
Authorization: Bearer {{access_token}}
Body
{
"query":"mutation DeactivateUser($globalUserId: UUID!) {deactivateUser(globalUserId: $globalUserId) { globalUserId}}",
"variables":{
"globalUserId":"{{user_id}}"
}
}
Reactivate User
Replace the {{user_id}} with the id of the user which should be reactivated.
POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1
Header
Content-Type: application/json
Authorization: Bearer {{access_token}}
Body
{
"query":"mutation reactivateUser($globalUserId: UUID!) {reactivateUser(globalUserId: $globalUserId) { globalUserId}}",
"variables":{
"globalUserId":"{{user_id}}"
}
}
Delete User (Anonymize)
Replace the {{user_id}} with the id of the user which should be anonymized. This will deactivate the user and schedule the deletion for 14 days in the future. This allows for a grace period of 2 weeks until which a delete action can be undone. Once the 2 weeks have passed, the user becomes unrecoverable forever.
POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1
Header
Content-Type: application/json
Authorization: Bearer {{access_token}}
Body
{
"query":"mutation deleteUser($globalUserId: UUID!) {deleteUser(globalUserId: $globalUserId) { globalUserId}}",
"variables":{
"globalUserId":"{{user_id}}"
}
}
Cancel Delete
Replace the {{user_id}} with the id of the user for which anonymization should be cancelled. This will only work during the 2 week grace period after a delete was initiated.
POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1
Header
Content-Type: application/json
Authorization: Bearer {{access_token}}
Body
{
"query":"mutation cancelDelete($globalUserId: UUID!) {cancelDelete(globalUserId: $globalUserId) { globalUserId}}",
"variables":{
"globalUserId":"{{user_id}}"
}
}
Create User
Adjust the variables for the user (firstname, lastname, email).
POST https://{{base_domain}}/accounts/api/v1/graphql HTTP/1.1
Header
Content-Type: application/json
Authorization: Bearer {{access_token}}
Body
{
"query":"mutation createUser($createUserInput: CreateUserInput!) { createUser(input: $createUserInput) { globalUserId }}",
"variables":{
"createUserInput":{
"firstname":"{{first_name}}",
"lastname":"{{last_name}}",
"email":"{{email}}",
"externalId":"{{externalId}}"
}
}
}
Updated 2 months ago