Users and UserGroups Declarative API Interface

This article explains how to use the declarative API interface to manage users and user groups. For a high-level overview of the declarative API interface, please refer to the declarative API interface documentation.

Managing Users

The declarative API interface for users allows you to manage all user entities at once. The declarative API interface for users has the following endpoint:

  • /api/layout/users

The default hostname for the application endpoint is determined by which edition of GoodData.CN you use:

  • GoodData.CN Production K8S Edition
    https://{organization-hostname}/api/layout/users
  • GoodData.CN Community Edition
    http://localhost:{port}/api/layout/users

Where:

  • {organization-hostname}
    Specifies the hostname for your organization with GoodData.CN Production K8S Edition. For example gooddata.com.
  • {port}
    Specifies the port to access your installation of GoodData.CN Community Edition. The default port is 3000.

User Details Considerations

GoodData.CN expects all user details to be managed and stored in an external OIDC compatible service. The only details about users that are stored within the GoodData.CN platform are the user ID, the user authentication ID for the OIDC authentication provider, and any groups that the user belongs to.

Write Operations

The following details must be present in the declarative payload when you issue a PUT request:

  • The adminUser that was used to create the bootstrap token for the organization must always be present.
  • The authentication identifier (authId) so that users can be authenticated through the OIDC provider.

Example Requests

The examples in this section are not meant to be used without modification. Please modify the examples to match the requirements of your site before using them.

Retrieve All Users

The following example retrieves all of the users in your organization and stores the output in a JSON file named users-layout.json.

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  $HOSTNAME/api/layout/users > users-layout.json

Restore or Redefine All Users

The following example replaces the user layout for the organization with that of a previously retrieved layout.

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X PUT \
  $HOSTNAME/api/layout/users -d @users-layout.json

Users Layout Document Structure

The following example shows the layout for users when you issue a GET request to the declarative endpoint. AuthId is replaced by a dummy value.

{
   "users" : [
     {
       "id" : "admin",
       "userGroups" : [
         {
           "id" : "adminGroup",
           "type" : "userGroup"
         }
       ]
     },
     {
       "authId": "<your-client-id>",
       "id": "test",
       "userGroups" : [
         {
           "id" : "develGroup",
           "type" : "userGroup"
         }
       ]
     }
   ]
}

Managing User Groups

The declarative API interface for users allows you to manage all user groups entities at once. The declarative API interface for users groups has the following endpoint:

  • /api/layout/userGroups

The default hostname for the application endpoint is determined by which edition of GoodData.CN you use:

  • GoodData.CN Production K8S Edition
    https://{organization-hostname}/api/layout/userGroups
  • GoodData.CN Community Edition
    http://localhost:{port}/api/layout/userGroups

Where:

  • {organization-hostname}
    Specifies the hostname for your organization with GoodData.CN Production K8S Edition. For example gooddata.com.
  • {port}
    Specifies the port to access your installation of GoodData.CN Community Edition. The default port is 3000.

User Groups Details Considerations

The only details available for the user groups are the identifier and a list of parents (user groups).

Write Operations

The user group that was used to create the bootstrap token for the organization must always be present in the declarative payload when you issue a PUT request.

Example Requests

The examples in this section are not meant to be used without modification. Please modify the examples to match the requirements of your site before using them.

Retrieve All User Groups

The following example retrieves all of the user groups in your organization and stores the output in a JSON file named userGroups-layout.json.

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  $HOSTNAME/api/layout/userGroups > userGroups-layout.json

Restore or Redefine All User Groups

The following example replaces the user group layout for the organization with that of a previously retrieved layout.

curl -H "Authorization: Bearer YWRtaW46Ym9vdHN0cmFwOmFkbWluMTIz" \
  -H "Content-Type: application/json" \
  -X PUT \
  $HOSTNAME/api/layout/userGroups -d @userGroups-layout.json

User Groups Layout Document Structure

The following example shows the layout for user groups when you issue a GET request to the declarative endpoint.

{
   "userGroups" : [
      {
         "id" : "adminGroup"
      },
      {
         "parents" : [
            {
               "id" : "adminGroup",
               "type" : "userGroup"
            }
         ],
         "id" : "develGroup"
      }
   ]
}
User and UserGroup Entity Interface
Manage User and UserGroups Together