Manage Organizations

This article explains how to use the API interfaces to manage an organization. For a high-level overview of the API interfaces, please refer to the API documentation .

Organization Entity API Interface

The entity endpoint for an organization returns the definition of the organization. The entity API interface for an organization uses the following endpoint:

  • api/entities/organization

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/entities/organization
  • GoodData.CN Community Edition
    http://localhost:{port}/api/entities/organization

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.

Organization Declarative API Interface

The declarative API interface allows you to manage all of the entities in an organization at once. When you call the organization declarative API interface, you return all the entities within the organization that are associated with the host name. The declarative API interface for an organization uses the following endpoint:

  • /api/layout/organization

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/organization
  • GoodData.CN Community Edition
    http://localhost:{port}/api/layout/organization

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.

Permissions Definition

The only API the user can define or modify the permission settings for the organization is the declarative API of the organization. In the section permissions is a list of permission definitions where particular permission is granted to the assignee (user or user-group).

  • For further details see the topic Manage permissions.
  • The user group that was used to create the bootstrap token for the organization must always be present.

Security Considerations

The following information is not returned when you call /api/layout/organization:

  • The secret token for the organization
  • Data Source passwords

You can PUT all entities available to the organization with the following restrictions:

  • Because the secret token for an organization is not retrieved when you submit a GET request for the organization declarative layout, the organization secret token must be specified in the retrieved document before you submit a PUT request.
  • You must either specify the username and password for the Data Sources associated with the organization in the PUT request or specify nothing at all.

Write Operations

Organization Declarative API Interface 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 the Organization Declarative Layout

The following example returns all the entities associated with the organization that is specified in the hostname of the call and stores the output in a JSON file named organization-layout.json:

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

Organization Declarative Layout Document Structure

The following examples show the contents of the output that is returned when you call the /api/layout/organization endpoint. To avoid a large example, all the components are left empty. You can view the component definitions under their particular section in the layout endpoints section of the API reference. The value of oauthClientSecretattribute can’t be retrieved.

Declarative Layout with an External OIDC Provider

In the following example, the values for oauthClientId, oauthClientSecret, and oauthIssuerLocation are replaced by dummy values.

{
  "dataSources": [],
  "organization": {
    "hostname": "localhost",
    "name": "Good Organization",
    "id": "org1",
    "oauthClientId": "<client-id>",
    "oauthClientSecret": "<secret>",
    "oauthIssuerLocation": "<url>",
    "permissions": [
      {
        "assignee": {
          "id": "<bootstrap-group-id>",
          "type": "userGroup"
        },
        "name": "MANAGE"
      }
    ]
  },
  "users": [],
  "userGroups": [],
  "workspaceDataFilters": [],
  "workspaces": []
}

Declarative Layout with an Internal OIDC Provider

In the following example, the value of oauthClientIdattribute is replaced by a dummy value in the example.

{
  "dataSources": [],
  "organization": {
    "hostname": "localhost",
    "name": "Good Organization",
    "id": "org1",
    "oauthClientId": "<client-id>",
    "permissions": [
      {
        "assignee": {
          "id": "<bootstrap-group-id>",
          "type": "userGroup"
        },
        "name": "MANAGE"
      }
    ]
  },
  "users": [],
  "userGroups": [],
  "workspaceDataFilters": [],
  "workspaces": []
}

When updating the organization declarative layout while using an internal OIDC authentication provider, it is not necessary to specify any of the following attributes as they are automatically retrieved from the provider:

  • oauthIssuerLocation
  • oauthClientId
  • oauthClientSecret

Restore or Modify the Organization Declarative Layout

The following example uses the previously retrieved declarative layout from a call to the /api/layout/organization endpoint to restore the organization to the state defined within the file:

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

Managing Entities in an Organization

Each entity or item within the organization model can be defined and changed individually through their related entity API endpoint. To learn all available entity endpoints, see the endpoints for entities in the API reference.

Some entities can be managed through their related API endpoint using a declarative interface. For more information on managing entities within an organization by using the declarative API interface, see the following documentation:

Create Organizations
Enable CORS For an Organization