Scopes and permissions

Understand the permissions required for various API actions.

Scopes define the level of access your API credentials have. This guide explains how scopes work and how to manage them at both the company and credential levels.

Scopes overview

Our API endpoints use scopes to manage access. Each endpoint requires a specific scope, but a single scope (like users:read) can grant access to multiple related endpoints.

Scopes follow the format resource:action, where:

• resource refers to the accessed item, such as users, groups, courses, or paths.
• action specifies the permitted operation on the resource, which can be:
  • read: Retrieve data.
  • write: Create, update, or delete data.
  • bulk: Perform bulk operations.

For example, users:read grants read-only access to user-related resources; while groups:bulk allows bulk actions on groups.

📚

For endpoint-specific scope requirements, refer to the API reference.

Managing scopes

You can manage scopes at 2 levels:

• Company level: For broad organizational oversight.
• Credential level: For granular permissions for each API credential.

Company-level scopes

This level sets the maximum available scopes for your entire organization. It acts as a "ceiling" of permissions that any of your API credentials can potentially possess.

We automatically grant your organization a set of default scopes when you first get API access. These scopes provide access to the most common API endpoints, but they exclude endpoints for the Bulk API, Skills, and Webhooks.

✏️

To change company-level scopes

Contact your Customer Success Partner (CSP). They can:

• Add any company-level scopes you need, such as those for advanced endpoints like the Bulk API. Added scopes are not automatically applied to existing credentials. You’ll need to manually update your credentials to use them. For step-by-step instructions, see Manage API credentials.
• Restrict company-level scopes. Company-level restrictions are automatically applied to all API credentials.

💡

You don’t need to generate a new token when updating API credentials. Scopes changes take effect immediately, and existing tokens will reflect the updated permissions.

Credential-level scopes

Each API credential can have a custom subset of the scopes available at the company level.

✏️

To change credential-level scopes

Platform owners and admins can edit API credentials on the API v2 admin dashboard to apply different credential-level scopes. For step-by-step instructions, see Manage API credentials.

💡

You don’t need to generate a new token when updating API credentials. Scopes changes take effect immediately, and existing tokens will reflect the updated permissions.

Troubleshooting access errors

If your API request returns a 403 error with "error": "invalid_scope", it means your credentials are missing the necessary scope for that endpoint.

To resolve this issue:

1. Identify the required scope: Check the endpoint's documentation in the API reference to find the specific scope it requires.
2. Request the missing scope:
   1. Contact your platform owner or platform admin to request the missing scope. They can edit the credential-level scopes directly from the API v2 admin dashboard. See Manage API credentials for more information.
   2. If the required scope is not available at the company level, your admin will need to contact your Customer Success Partner (CSP) to have it added.