Use Organization API

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 Declarative API Interface

GoodData follows an API-first approach and as such you can fetch all of your GoodData. 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 /api/v1/layout/organization endpoint.

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 OIDC Provider

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

{
  "dataSources": [],
  "organization": {
    "colorPalettes": [],
    "cspDirectives": [],
    "hostname": "localhost",
    "name": "Good Organization",
    "id": "org1",
    "jitEnabled": true,
    "oauthClientId": "<client-id>",
    "oauthClientSecret": "<secret>",
    "oauthIssuerId": "myOIDCprovider",
    "oauthIssuerLocation": "<url>",
    "oauthSubjectIdClaim": "oid",
    "permissions": [
      {
        "assignee": {
          "id": "<bootstrap-group-id>",
          "name": "Some User Group",
          "type": "userGroup"
        },
        "name": "MANAGE"
      }
    ],
    "settings": [],
    "themes": []
  },
  "users": [],
  "userGroups": [],
  "workspaceDataFilters": [],
  "workspaces": []
}

If you want to update an existing organization, send a PATCH request with the following payload to the /api/v1/entities/admin/organizations/{id} endpoint:

{
  "data": {
    "attributes": {
      "allowedOrigins": [
        "string"
      ],
      "earlyAccess": "string",
      "hostname": "string",
      "jitEnabled": true,
      "name": "string",
      "oauthClientId": "string",
      "oauthClientSecret": "string",
      "oauthIssuerId": "myOidcProvider",
      "oauthIssuerLocation": "string",
      "oauthSubjectIdClaim": "oid"
    },
    "id": "id1",
    "type": "organization"
  }
}

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": {
    "colorPalettes": [],
    "cspDirectives": [],
    "hostname": "localhost",
    "name": "Good Organization",
    "id": "org1",
    "oauthClientId": "<client-id>",
    "permissions": [
      {
        "assignee": {
          "id": "<bootstrap-group-id>",
          "name": "Some User Group",
          "type": "userGroup"
        },
        "name": "MANAGE"
      }
    ],
    "settings": [],
    "themes": []
  },
  "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

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.
Note
This restriction does not apply when you use an internal OIDC authentication provider.
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.

Updating Your Organization's Settings

Several settings within your organization, such as user data filters or your preferred starting day of the week, are stored in cache. When you update these settings, be aware there is a brief delay (typically a few seconds) before the new settings replace the cached ones and take effect.

Write Operations

Because the declarative API interface manages all of the organization entities at once, the contents of any PUT request that uses the declarative API interface to affect the layout of an organization will completely replace the contents of the existing layout. Please back up your model before executing any write operations.

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

Example of an organization entity:

{
    "id": "nmvkoddfzwy3mz",
    "type": "organization",
    "attributes": {
        "name": "johnsmith Internal",
        "hostname": "johnsmith.playground.gooddata.com",
        "oauthIssuerLocation": "https://auth.cloud.gooddata.com/",
        "oauthClientId": "o7r2PEaUmkKiymKnY2pp8mONKnY2pp82U",
        "oauthIssuerId": "auth0"
    }
}

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 Workspace Declarative API Interface.

Backup and Restore an Organization

Similar to workspaces and datasources, it’s important to have a backup of your organization configuration to ensure smooth recovery in case of any unforeseen issues. With the declarative API, backing up and restoring an organization is now more intuitive.

Back Up an Organization

To back up the organization configuration:

Use the following API call to retrieve the current configuration of the organization:
```
curl -X GET \
  $HOST_URL/api/v1/layout/organization \
  -H 'Authorization: Bearer $API_TOKEN'
```
This command will fetch the entire organization configuration in a declarative layout.
Store the returned JSON output securely as your backup.

Restore an Organization

To restore an organization using a backup:

Ensure you have the backup JSON of your organization configuration at hand.
Before restoring, make sure the backup is compatible with the current API version and contains all the necessary fields.

Use the following API call to restore the organization configuration from your backup:

curl -X PUT \
  $HOST_URL/api/v1/layout/organization \
  -H 'Authorization: Bearer $API_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-binary @path_to_your_backup.json

Replace path_to_your_backup.json with the path to your backup JSON file.

Warning

Restoring an organization will replace the current configuration in its entirety. Ensure you review and verify the backup content before restoring to prevent unintentional data loss.

Always remember to test backups in a staging environment before applying them to a production organization.

Create and Restore Backups