Users Entity API Interface

In this article, we provide basic examples of user and user group management. To see the entire API specification, go to API reference.

Be aware of your application endpoint. In the case of Helm Chart deployment, use the value https://<organization-hostname>. For the All-in-One docker image, the default endpoint is http://localhost:3000. In the examples below, we use the variable $HOST_URL to represent the endpoint.

User Management

• Using the entity interface, you can create, modify, or delete individual users.
• To accurately set up a user, it’s essential to have their authenticationId. For more information on authenticationId, see the Authentication section.
• If you are updating a user, you can change their user groups and authentication ID. Their identifier cannot be changed.

Examples of User Management

Create a User

This example demonstrates how to create a new user with the provided information, including their authentication ID, email, first name, and last name. The user is also assigned to the adminGroup.

Assuming that the adminGroup was created during the organization’s setup:

curl --request POST \
  --header "Authorization: Bearer $API_TOKEN" \
  --header 'Content-Type: application/vnd.gooddata.api+json' \
  --data '{
      "data": {
        "id": "john.doe",
        "type": "user",
        "attributes": {
          "authenticationId": "<auth-id>",
          "email": "<email>",
          "firstname": "<first-name>",
          "lastname": "<last-name>"
        },
        "relationships": {
          "userGroups": {
            "data": [ {
              "id": "adminGroup",
              "type": "userGroup"
            } ]
          }
        }
      }
}' $HOST_URL/api/v1/entities/users

Retrieve all Users

To retrieve a list of all users, use the paged entities API by sending a GET request to /api/v1/entities/users. If there are more users than can be displayed on a single page, you can follow the next link provided in the response to access the remaining users.

curl --request GET \
  --header "Authorization: Bearer $API_TOKEN" \
  $HOST_URL/api/v1/entities/users

If you want to see the user groups associated with each user, specify the include parameter in your request: /api/v1/entities/users?include=userGroups

Retrieve a User

To retrieve information about a specific user, use the following GET request:

curl --request GET \
  --header "Authorization: Bearer $API_TOKEN" \
  $HOST_URL/api/v1/entities/users/john.doe

If you want to see the user groups associated with this user, specify the include parameter in your request: /api/v1/entities/users/john.doe?include=userGroups

Update a User

To update user information, you can use either a PATCH or PUT request, depending on your specific needs.

• Use PATCH if you want to modify the content of a user, such as their name or email address. Note that PATCH doesn’t set the user’s group relationships; it only updates the user’s content.
• Use PUT if you want to update the groups that the user is part of. When using PUT, you must provide a complete list of all the groups the user should belong to, not just the new additions.

Here’s an example using PUT to update user information:

curl --request PUT \
  --header "Authorization: Bearer $API_TOKEN" \
  --header 'Content-Type: application/vnd.gooddata.api+json' \
  --data '{
      "data": {
        "id": "john.doe",
        "type": "user",
        "attributes": {
          "authenticationId": "<auth-id>",
          "email": "<email>",
          "firstname": "<first-name>",
          "lastname": "<last-name>"
        },
        "relationships": {
          "userGroups": {
            "data": [ {
              "id": "adminGroup",
              "type": "userGroup"
            } ]
          }
        }
      }
  }' $HOST_URL/api/v1/entities/users/john.doe

Delete a User

curl --request DELETE \
  --header "Authorization: Bearer $API_TOKEN" \
  $HOST_URL/api/v1/entities/users/john.doe

User Group Management

• Using the entity interface, you can create, update, or remove individual user groups.
• User groups can be nested within other user groups.
• If you are updating a user group, you can only change the parent groups. Its identifier cannot be changed.

Examples of User Group Management

Create a User Group

curl --request POST \
  --header "Authorization: Bearer $API_TOKEN" \
  --header 'Content-Type: application/vnd.gooddata.api+json' \
  --data '{
      "data": {
        "attributes" : {
          "name": "New User Group"
        },
        "id" : "develGroup",
        "type" : "userGroup"
      }
}' $HOST_URL/api/v1/entities/userGroups

Retrieve all User Groups

To retrieve a list of all user groups, use the paged entities API by sending a GET request to /api/v1/entities/userGroups. If there are more user groups than can be displayed on a single page, you can follow the next link provided in the response to access the remaining groups.

curl --request GET \
  --header "Authorization: Bearer $API_TOKEN" \
  $HOST_URL/api/v1/entities/userGroups

To view parent user groups, you must specify the include parameter: /api/v1/entities/userGroups?include=parents.

Retrieve a User Group

You can retrieve information about a specific user group using the following GET request:

curl --request GET \
  --header "Authorization: Bearer $API_TOKEN" \
  $HOST_URL/api/v1/entities/userGroups/develGroup

To view parent user groups, you must specify the include parameter: /api/v1/entities/userGroups/develGroup?include=parents

Update a User Group

To update user group information, you can use either a PATCH or PUT request, depending on your specific needs. See the Update a User section for more details.

Assuming that the adminGroup was created during the organization’s setup:

curl --request PUT \
  --header "Authorization: Bearer $API_TOKEN" \
  --header 'Content-Type: application/vnd.gooddata.api+json' \
  --data '{
      "data": {
        "attributes" : {
          "name": "Some User Group"
        },
        "id" : "develGroup",        
        "type" : "userGroup",
        "relationships": {
          "parents": {
            "data": [ {
              "id": "adminGroup",
              "type": "userGroup"
            } ]
          }
        }
      }
}' $HOST_URL/api/v1/entities/userGroups/develGroup

Delete a User Group

curl --request DELETE \
  --header "Authorization: Bearer $API_TOKEN" \
  $HOST_URL/api/v1/entities/userGroups/develGroup