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/v1/entities/organization

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

  • GoodData.CN
    https://{organization-hostname}/api/v1/entities/organization
  • GoodData.CN Community Edition
    http://localhost:{port}/api/v1/entities/organization

Where:

  • {organization-hostname}
    Specifies the hostname for your organization with GoodData.CN. 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/v1/layout/organization

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

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

Where:

  • {organization-hostname}
    Specifies the hostname for your organization with GoodData.CN. 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/v1/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/v1/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/v1/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/v1/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/v1/layout/organization -d @organization-layout.json

View Entitlements

Depending on the type of license or hosted organization you are using, your GoodData environment may come with certain entitlements:

  • Contract (non-public) defines how long you can use the organization for before you have to renew the contract. Note that you can host multiple organisations in the same deployment. While your deployment expires when your license expires, individual organizations expire according to their contract expiration dates. Contracts are only used for GoodData Cloud.
  • Tier (public) defines the level of service you have access to. Currently the tier entitlement is used to differentiate between the trial and enterprise tiers of GoodData.
  • CustomTheming (public) defines whether you can modify the visual style of your GoodData deployment.
  • WorkspaceCount or UnlimitedWorkspaces (non-public) defines the maximum number of workspaces an organization can have.
  • UserCount or UnlimitedUsers (non-public) defines the maximum number of users an organization can have.

There are two API endpoints that let you view your entitlements:

  • /api/v1/entities/entitlements may return the following organizational entitlements:

    • Contract
    • Tier
    • WorkspaceCount or UnlimitedWorkspaces
    • UserCount or UnlimitedUsers

  • /api/v1/actions/resolveEntitlements aggregates organizational entitlements, as well as entitlements taken from the license and any other stand-alone entitlements:

    • Contract taken from organization
    • Tier taken from organization
    • WorkspaceCount or UnlimitedWorkspaces taken from organization or license
    • UserCount or UnlimitedUsers taken from organization or license
    • CustomTheming a stand-alone entitlement

View Usage

To be able to easily monitor how many workspaces and users you currently have in your organization, use the /api/v1/actions/collectUsage API endpoint. This API returns the following items:

  • WorkspaceCount shows how many workspaces currently exist in your organization
  • UserCount show how many users currently exist in your organization

Note that the organization MANAGE permission is required to make this API call.

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