System Keys BETA

System Keys allow you to centrally manage API keys, giving you the ability to audit and govern usage of them with your account.

You can obtain the system key and secret values using the Create System Key endpoint. You can regenerate the system key value using the Rotate System Key endpoint.

Limitations

System keys currently can only be managed with user keys. It requires the Account Administrator role for the user.

Resource types

The following resource types are supported:

ACCOUNT - Connector type endpoints.
USER - User Management endpoints.
ROLES - Role Management endpoints.
WEBHOOK - Webhook Management endpoints.
TEAM - Team Management endpoints.
PRIVATE_LINK - Private Link Management endpoints.
PROXY - Proxy Agent Management endpoints.
REMOTE_EXECUTION_AGENT - Hybrid Deployment Agent Management endpoints.
TRANSFORMATION - dbt Transformation Management endpoints.
DESTINATION - Destination Management and Group Management endpoints.
CONNECTOR - Connector Management and Connector Schema Management endpoints.

The DESTINATION and CONNECTOR resource types supports granular access rules. Read on to understand these granular rules.

Access levels

The following access levels are supported:

NONE - Access to resource type is restricted.
READ - Read access to resource type.
MANAGE - Full access to resource type.

Access rules types

There are the following types of access rules:

General - Access rule is applied to all entities.
Entity-level - Access level is applied only to a particular entity.
Group-level - Access level is applied to all entities in a particular group.

Entity-level rules

For the CONNECTOR and DESTINATION resource types, access rules for particular entities can be created.

Entity-level access rules override general rules.

For example, there are three rules created:

{
  "permissions": [
    {
       "resource_type": "CONNECTOR",
       "access_level": "READ"
    },
    {
       "resource_type": "CONNECTOR",
       "access_level": "NONE",
       "resource_filter": {
           "ids": ["connector_id_1", "connector_id_2"]
       }
    },
    {
       "resource_type": "CONNECTOR",
       "access_level": "MANAGE",
       "resource_filter": {
           "ids": ["connector_id_3", "connector_id_4"]
       }
    }
  ]
}

This results in:

For connectors with IDs "connector_id_1" and "connector_id_2" access will be restricted (access level NONE).
For connectors with IDs "connector_id_3" and "connector_id_4", full access will be granted (access level MANAGE).
For all other connectors, access level READ will be granted.

Group-level rules

For the CONNECTOR and TRANSFORMATION resource types, access rules for all entities in the group can be created.

Group-level access rules override general rules, but entity-level rules override group-level rules.

For example, there are three rules created:

{
  "permissions": [
    {
        "resource_type": "CONNECTOR",
        "access_level": "READ"
    },
    {
        "resource_type": "CONNECTOR",
        "access_level": "NONE",
        "resource_filter": {
          "group_ids": ["group_id_1"],
          "ids": ["connector_id_1"]
        }
    },
    {
      "resource_type": "CONNECTOR",
      "access_level": "MANAGE",
      "resource_filter": {
        "ids": [
          "connector_id_2"
        ]
      }
    }
  ]
}

This results in:

For connector with ID "connector_id_2", full access is granted (even it’s in group “group_id_1”).
For connector with ID "connector_id_1" and all connectors in group "group_id_1" (except "connector_id_2"), access is restricted (access level NONE).
For all other connectors, access level READ will be granted.

Group-level rules scenario

You can create a separate group for each of your environments. Then you create a key for each group. Each key allows you to access and create connectors only in its group.

Let's say you created the following groups for the following environments:

A group with the ID dev_group_id for the development environment.
A group with the ID staging_group_id for the staging environment.
A group with the IDs prod_group_id_1 and prod_group_id_2 for the production environment.

You can create three separate keys to manage connectors in each environment.

Create a key for the development environment:

{
  "permissions": [
    {
       "name": "dev_key",
       "resource_type": "CONNECTOR",
       "access_level": "MANAGE",
       "resource_filter": {
           "group_ids": ["dev_group_id"]
       }
    }
  ]
}

Create a key for the staging environment:

{
  "permissions": [
    {
       "name": "staging_key",
       "resource_type": "CONNECTOR",
       "access_level": "MANAGE",
       "resource_filter": {
           "group_ids": ["staging_group_id"]
       }
    }
  ]
}

Create a key for the production environment:

{
  "permissions": [
    {
       "name": "prod_key",
       "resource_type": "CONNECTOR",
       "access_level": "MANAGE",
       "resource_filter": {
           "group_ids": ["prod_group_id_1", "prod_group_id_2"]
       }
    }
  ]
}

Each key can only manage connectors in its group, which corresponds to the relevant environment.

Filtering in list endpoints

Get dbt projects list

The result contains only dbt projects from groups for which the system key has READ or MANAGE access level.

Get all groups

The result contains only groups for which the system key has READ or MANAGE access level.

Get all connectors in group

The result contains only connectors for which the system key has READ or MANAGE access level.

Get team memberships in groups

The result contains only team membership info for groups for which the system key has READ or MANAGE access level.

Get team memberships in connectors

The result contains only team membership info for connectors for which the system key has READ or MANAGE access level.

Get user memberships in groups

The result contains only user membership info for groups for which the system key has READ or MANAGE access level.

Get user memberships in connectors

The result contains only user membership info for connectors for which the system key has READ or MANAGE access level.

Get webhooks list

The result contains only account webhooks if the system key has READ or MANAGE access level for the WEBHOOK resource type and group webhooks for groups for which system key has READ or MANAGE access level.