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.

Understand scope levels

Scopes work in two levels:

1. Company-level scopes define what's available across your organization (the permission ceiling)
2. Credential-level scopes assign subsets of company scopes to individual API credentials

Example: If company-level scopes include users:read, users:write, and groups:read, you might configure:

• Analytics credential: users:read only
• HR sync credential: users:read, users:write, groups:read

You cannot assign a scope to a credential unless it exists at the company level first.

Manage scopes

Company-level scopes

Company-level scopes define the maximum permissions available to any API credential in your organization. Individual credentials can only use scopes that exist at the company level.

By default, your organization receives all available scopes when you first get API access.

View company-level scopes

Platform owners and platform admins can view company-level scopes, but cannot modify them directly. To add or restrict company-level scopes, contact your Customer Success Partner (CSP).

To view your current company-level scopes:

1. Log in ↗ to your 360Learning account.
2. In the left sidebar, hover over the platform group, then click Settings (the gear icon).
3. In the left sidebar, click API v2.
4. Next to any credentials, click the pen icon (Edit).

All scopes displayed (both checked ☑ and unchecked ☐) represent your company-level scopes:

• Selected scopes (☑) are assigned to this specific credential.
• Unselected scopes (☐) are available at the company level but not assigned to this credential.

Add company-level scopes

To add new scopes at the company level, contact your Customer Success Partner (CSP) with the specific scopes you need (e.g., users:write, groups:bulk.

Once your CSP adds the scopes:

• New scopes become available for use, but 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

You may want to restrict company-level scopes to enforce security policies or limit API access across your organization. For example, you might remove write or bulk scopes if your integration only requires read access.

When you restrict company-level scopes:

• Credentials using the restricted scope will immediately lose access.
• Any API requests requiring that scope will return with a 403 error.
• The restrictions apply organization-wide and cannot be overridden at the credential level.
• Restricted scopes cannot be re-added without contacting your CSP again

Before requesting scope restrictions, audit your existing API credentials to identify anything that will be affected.

Step 1: Audit existing credentials

1. Log in ↗ to your 360Learning account.
2. In the left sidebar, hover over the platform group, then click Settings (the gear icon).
3. In the left sidebar, click API v2.
4. Review the scopes assigned to each active credential.
5. Identify which credentials use the scopes you plan to restrict.
6. Update or disable those credentials before proceeding.

Restricting a scope in use will immediately break those integrations.

Step 2: Contact your Customer Success Partner (CSP)

After completing the audit, contact your CSP with:

• The scopes you want to remove
• Confirmation that you've audited existing credentials.

Credential-level scopes

Each API credential can have a custom subset of the scopes available at the company level. This allows you to follow the principle of least privilege by granting each credential only the permissions it needs.

Platform admins and admins can see and edit API credentials on the API v2 admin dashboard. For step-by-step instructions, see Manage API credentials.

Edit credential-level scopes

Scope changes take effect immediately. You don't need to regenerate access tokens.

Troubleshoot 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 add the scope at the credential level. They can edit 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.