Managing API key roles and scopes

Split enables you to restrict the access level of API keys in two ways:

1. Specifying roles for the API key: This limits what resource types an API key can access
2. Specifying a scope for the API key: This limits the reach of the API key across environments, a workspace, or the whole organization.

While Split client-side and server-side SDK API keys are always scoped to a specific environment, Admin API keys can be tuned to granular access levels by creating them with a role and scope using the Split API. This page describes the roles and scopes that can be applied when creating Admin API keys.

Choose the right role

The role given to an Admin API key aims to limit the access and operations a key can perform within Split within two functional areas: Administrative Permissions and Resource (Feature Flag & Segment) Permissions.

Note that roles can be combined together at the time an API key is created to provide the appropriate set of permissions needed to accomplish specific tasks.

Choose the right scope

An API key can be scoped to limit its reach to:

• Specific environment(s): The API key will grant access to manage the resources (flags, segments, etc.) only within the specific set of environments that are enumerated at the time the API key is created.
• A specific workspace: The API key will grant access to manage the resources (flags, segments, traffic types, etc.) within only a single workspace. Access is also granted to manage future environments created within that workspace.
• The whole organization: The API key will grant access to reach resources across the whole organization. Granted access is effectively unscoped.

Create a restricted API key

You can use the Split API to create an Admin API key that has a restricted role or that leverages workspace and environment scopes. You can also restrict scope of an Admin API key to specific environments in the Web Console. Both approaches are described below.

Using the Split API to manage roles and scopes

Roles and scopes are assigned to an Admin API key ("apiKeyType": "admin") at the moment of its creation via the Split API. Create an API key

Some important considerations:

• Roles and scopes are not editable. A role or scope cannot be changed for an API key after it is created.
• An Admin API Key cannot be used to create another with a broader scope than its own. When creating a new API key, the API key used to authenticate the request must have an equal or greater scope than the scope of the new API key.
• In order to create a new API key, the API key used to authenticate the request must have either the API_ALL_GRANTED and/or the API_APIKEY role assigned.
• If no value is specified, by default the API_ALL_GRANTED role is assigned.
• If no scope is specified, by default the organization-wide scope is assigned.

The POST API Key endpoint takes a JSON attribute, used to pass in the desired role. For an Admin key with full permissions, here’s a sample payload you can send to create the role and its expected response.

POST: /internal/api/v2/apiKeys
{
  "name": "my_first_restricted_apikey",
  "apiKeyType": "admin",
  "workspace": null,
  "environments": [],
  "roles": ["API_ALL_GRANTED"] 
}

Response:
{
  "organization": {
    "type": "Organization",
    "id": "your-org-id"
  },
  "environments": [
    {
      "type": "Environment",
      "id": "<<GLOBAL>>"
    }
  ],
  "name": "my_first_restricted_apikey",
  "createdBy": {
    "type": "api_key",
    "id": "641mm**********************"
  },
  "createdAt": 1682722168424,
  "apiKeyType": "admin",
  "roles": [
    "API_ALL_GRANTED"
  ],
  "type": "api_key",
  "key": "b9lnhf***************************"
}

Be sure to copy your Admin API key (Line 34 in above example) once it's generated. For security purposes, you won't see the key again.

This is another example of a request to create an Admin API key that is scoped to a workspace.

POST: /internal/api/v2/apiKeys`
{
  "name": "my_workspace_admin_api_key",
  "apiKeyType": "admin",
  "workspace": {
     "type": "workspace",
     "id": "your-workspace-id"
  },
  "environments": [],
  "roles": ["API_WORKSPACE_ADMIN"]
}

Response:
{
  "organization": {
    "type": "Organization",
    "id": "Your-Org-id",
  },
  "environments": [
     {
       "type": "environment",
       "id": "<<GLOBAL>>"
     }
  ],
  "name": "my_workspace_admin_api_key",
  "createdBy": {
    "type": "api_key",
    "id": "641mm**********************"
  },
  "createdAt": 1691762215442,
  "apiKeyType": "admin",
  "workspace": {
    "type": "workspace",
    "id": "Your-Workspace-id"
  },
  "roles": [
    "API_WORKSPACE_ADMIN"
  ],
  "type": "api_key",
  "key": "b9lnhf***************************"
}

Using the Web Console to manage scopes

You can also use the Admin settings section in the Split web console to create an Admin API key that is scoped to specific environment(s). At this time, you cannot use this UI to specify a specific role or workspace scope. Note that all SDK API keys are inherently scoped to a single environment.

Manage a restricted API key

You can revoke and clone restricted Admin API keys using the Split web console as you would an unrestricted key.

Ensure your key has the appropriate role to use the API endpoints

Each Split API endpoint has a list of accepted roles that the endpoint will look for on the bearer key that you used to authorize your API request. You can see the list of accepted roles by navigating to a specific resource in our API documentation. Additionally, error codes have been created for cases where requests do not have the appropriate role in the bearer token that was used.