User and UserGroup Entity Interface

User Management

  • Using the entity interface an individual user can be created, modified or deleted.
  • To properly define a user the authenticationId have to be known. For details on authenticationId see the Authentication section
  • When updating a user you can change user groups and authentication id only, identifier is immutable.

User Group Management

  • Using the entity interface an individual user group can be created, modified or deleted.
  • User group can be nested under other user groups.
  • When updating a user group you can change parent user groups only, identifier is immutable.

Examples

To see the entire API specification, visit API reference.

Be aware of your application endpoint. For Helm Chart deployment is used the https://<organization-hostname> value. For the All-in-One docker image, the default endpoint is http://localhost:3000. In the following examples the endpoint is substituted by $HOST_URL variable;

Create a User Group

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

Retrieve all User Group

You can retrieve all user groups via paged entities api /api/v1/entities/userGroups. If there are more user groups, then can fit in a single page follow the next link to retrieve remaining.

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

To see parents (user groups) you must specify the include parameter /api/v1/entities/userGroups?include=parents

Retrieve a User Group

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

To see parents (user groups) you must specify the include parameter /api/v1/entities/userGroups/develGroup?include=parents

Update a User Group

Assuming the adminGroup was created on bootstrap of an organization.

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

Create a User

Assuming the adminGroup was created on bootstrap of an organization.

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

You can retrieve all users via paged entities api /api/v1/entities/users. If there are more users, then can fit in a single page follow the next link to retrieve remaining.

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

To see user’s user groups you must specify the include parameter /api/v1/entities/users?include=userGroups

Retrieve a User

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

To see user’s user groups you must specify the include parameter /api/v1/entities/users/john.doe?include=userGroups

Update a User

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