API v2 - Limit API access with API Scopes

API scopes

1 What are API scopes?
2 What scopes are available as standard?
3 Creating a new API Scope
4 FAQs

Related Help Guide Pages

Integrate with the accessplanit API v2 Feeds - Overview

This page covers the purpose of API scopes and how to use them

API Scopes give you a simple, secure way to control exactly what level of access is available when building integrations using your accessplanit API v2 feeds. Instead of granting full API permissions every time you set up an integration, you can now define precisely which parts of your data an API user is allowed to see or interact with.

This is especially useful when working with third-party developers, by defining an API Scope, you can give partners access only to the specific information they need to build or maintain an integration, nothing more, and nothing less! It’s an easy way to protect your wider platform data while still building powerful connections across your systems.

In this guide, we’ll walk through how API Scopes work, why you might use them, and how to set them up in your accessplanit platform.

What are API scopes?

The section covers the purpose and ways that you can use API scopes

API Scopes let you control exactly what an API key can access in your accessplanit platform. Instead of giving every integration full visibility of your data, you can assign an API Scope to each API key to define the specific actions it can perform.

Key terms:

API Feed	An API Feed is a structured data source that allows external systems to read or update information in your platform. Each feed represents an area of your platform, e.g. ‘Courses’, ‘Bookings’.
API Key	An API Key acts as the ‘login details’ for an integration. It identifies who is connecting to your accessplanit platform and makes sure only authorised systems can access your API Feeds.
API Scope	An API Scope controls what an API Key can access. Scopes define which modules the integration can see, and whether it can create, read, update, or delete data. They let you limit each API Key to only the data required for its purpose, improving security and giving you full control over integration access.

You’re not limited to a single scope, your platform can have as many API Scopes as you need. This means you can create different access levels for different integrations, developers, or other internal uses.

Each API Scope is made up of granular permissions that allow you to control what data can be created, read, updated, and deleted. You choose these permissions from across your platform modules, giving you full flexibility.

For example:

For a website integration, you might create a scope that can read Courses and Course Dates, but cannot update or delete anything else
For a HR system integration, you might create a scope that can create, read, update, and delete Users and User Awards, but cannot access anything else
For a reporting integration, you could set a scope that offers read-only access to Bookings, Accounts, Invoices, Courses, Delegates, and Placeholders

By tailoring access in this way, API Scopes help you keep your data secure, minimise risk, and make sure every integration only interacts with the information it genuinely needs.

What scopes are available as standard?

This section outlines what API Scopes are already available in your platform and their purpose.

There are several API Scopes set up in every accessplanit platform, you can view these, but you cannot make any changes to them!

The first default API Scope is ‘API v2’, this scope has access to every API endpoint, this means it has full access to data available in your accessplanit API Feeds.

Please note

If there are any API Keys that were created in your platform before API Scopes were available, they will have the ‘API v2’ scope assigned to them

The remaining default scopes are designed for specific accessplanit integrations, such as Mailchimp and Power BI. These scopes are pre-configured and ready to use if you decide to enable those integrations in your platform. Their presence doesn’t mean the integrations are already active, it simply means the scopes are ready if you need them.

Creating a new API Scope

The section covers the basic steps for creating API Scopes in your accessplanit platform.

Access to create API Scopes

These are the requirements to be able to access the API Scopes functionality in your accessplanit platform

To gain access to create and manage API Scopes…

Your accessplanit platform must have the API v2 module enabled
Your User must have administrator access
Your User requires an additional role to provide you with access to the page

If you already have API v2, you can request access to API Scopes, please contact the Customer Success team at accessplanit, the team here will arrange for the required Users to have the additional role assigned to them!

Creating API Scopes

Open the ‘Administration’ menu from the Profile options at the top-right of your platform
Open the ‘API Scopes’ menu option to access the API Scopes DataGrid where you can add and manage Scopes for your API Keys
From the API Scopes DataGrid, click the ‘Add API Scope’ button
Provide your API Scope with a label
We recommend that the label includes the purpose, for example ‘Website Integration’
Choose whether this API Scope should ‘Allow’ or ‘Deny’ access to modules
1. Allow: Only the modules you select will be available
2. Deny: All modules are available except those you select
Leave the ‘Bypass API v2 Enabled Flag’ option unchecked
This option exists to support API Scopes that work with integrations outside of the API v2 module
Select which modules should be included or excluded, based on your allow or deny setting
- If you’ve chosen ‘Allow’, pick the modules the Scope should have access to
- If you’ve chosen 'Deny', pick the modules the Scope should not have access to, anything unselected will remain available
Run through this process for create, read, update, and delete permissions
Once you’ve completed the form, click ‘Save’ to create your API Scope

Associating your API Scopes to API Keys

Here is an explanation for how to assign an API Scope to an API Key to limit it’s access

Each API Key in your platform must have an API Scope assigned to it, to determine it’s access level.

To provide access to all data, use the standard “API v2” scope (ID: 10000)

To provide access to limited data, select the appropriate scope.

Associating your API Scopes for bearer token authentication

Here is an explanation for how to assign an API Scope to User or a Role to limit data access with bearer token authentication

Open your API Scopes DataGrid and find the API Scope that you would like to associate to a User or Role
Right click on this Scope and select ‘Members’ from the context menu options
Associate your API Scope to Users or Roles
Click ‘Save’ to save your changes
When Users, or Users with these Roles, make API calls using bearer token authentication, the data they can access will now be restricted according to the API Scope

FAQs

What’s the difference between an API Key and an API Scope?

An API Key identifies who is accessing your platform, while an API Scope defines what that API Key can do. Every API Key must have a Scope assigned to control the level of access available.

Can we limit access to data by Training Provider or Account Group?

No, API Scopes apply to entire modules, they can’t restrict access by Training Provider, Account Group, or any other groups or criteria.

Do I need an API Scope for every API Key?

Yes, all API Keys require an API Scope, whether that’s the full-access ‘API v2’ scope or a custom, restricted scope you create.

Can a single API Key have more than one API Scope?

Yes, you can assign multiple Scopes to the same API Key.

When you do this, the key will inherit the permissions from all assigned Scopes. For example, if one Scope grants access to one module and another Scope grants access to a different module, the API Key will be able to access both.

However, if any of the Scopes contradict each other, the Deny permission will always take priority. For instance, if one Scope allows access to the ‘Users’ module but another Scope denies it, the ‘Deny’ rule will override the Allow.

Can I copy or duplicate an API Scope?

Not at the moment, you will need to create a new Scope and reselect the permissions you require.

What happens if I delete an API Scope that an API Key is using?

The API Scope will no longer be available to reference, and the API Key will fallback to full API access.

Why do I need to choose permissions separately for create/read/update/delete?

By separating them you have full control! For example, you can provide read-only access to data while blocking updates or deletions.

Why can’t I edit the default API Scopes?

Default Scopes are locked because they are used by accessplanit integrations and must remain consistent to function correctly.

How do I know which modules a third-party integration needs access to?

Consider which areas of the platform your integration / developers need to be able to access, you’re unsure, you can start by testing with read-only access and add additional permissions as needed. Please speak to a member of the accessplanit team if you are stuck!

Can I test a Scope before assigning it to a live integration?

Yes, you can create a separate API Key, assign the new Scope, and test it in isolation (e.g. within Postman) without affecting your existing integrations.

What happens if I choose the wrong permissions, will it break my integration?

Possibly! If a required module or action is restricted, the API will return an authorisation error. You can adjust the Scope at any time if this happens. For data security, it is better to add additional access later, than to realise you have provided access to too much data and revoke access.

Is there a way to see which fields a module contains?

Yes, you can run a GET request to get a list of available fields for each module please check our dedicated guide: API v2 - Developer Resources | Viewing the available fields for each module for full details.

Can I set ‘read-only’ access for everything with an API scope?

Yes, you can grant read access to all modules for an integration while denying create, update, and delete permissions.

How do I know if the API v2 module is enabled on my platform?

Your Super Administrators or accessplanit Customer Success contact can confirm this! If you cannot see API Keys or API Scopes under Administration, you may not have the module enabled.

Which roles or permissions do I need to manage API Scopes?

If you have the API v2 module, to access API Scopes your Admin User will additionally need an extra role You need the API management role, assigned by accessplanit. Contact Customer Success if you require access.

Is API Scope functionality included in my contract, or is it an add-on?

API Scopes are available as part of the API v2 module. If you do not have API v2, limited-access Scopes may be available as a lower-cost option depending on your integration needs.

Do I need an API Scope if I’m only using accessplanit-built integrations?

Yes, but you won’t need to configure it. Default Scopes for built-in integrations are already provided.

Which standard API Scopes are linked to which integrations?

Scopes such as ‘Mailchimp’ and ‘Power BI’ link directly to those integrations, they are pre-set with the permissions required for those connections.

What’s the best Scope setup for a website integration?

Set your scope to ‘Allow'

Read → Courses, Course Dates
No create/update/delete

This keeps the integration secure and read-only.

What Scope should I use for Power BI or reporting tools?

Use the default ‘Power BI’ Scope, or create a custom read-only Scope that includes the modules you wish to report on, for example: Bookings, Accounts, Courses, Delegates.

Can I create a Scope just for specific fields only?

No, you assign permissions by module, so you cannot include some fields from a module and exclude others from the same module.

Do API Scopes impact API performance or rate limits?

No, API Scopes control authorisation only, they do not affect speed or request capacity.

How can I check which Scope a Key is currently using?

Open the API Key in your platform, the assigned Scope is displayed on the API Scopes option in the Details page.

How do I update a Scope without disrupting an existing integration?

Create a duplicate Scope with the new settings, assign it to a test Key, verify functionality, then swap it over on the live API Key when you’re ready.

Why can’t my developer access an module via the API feeds even though it’s selected for their API Scope?

Check that:

The correct action (read/update/create/delete) is selected
The Scope criteria isn’t set to “deny”
The integration isn’t using a different API Key with a different Scope

How can I remove API access for a specific third-party developer?

Remove or deactivate the API Key in the API Keys DataGrid. This immediately stops access for that integration.

What should I do if my integration suddenly stops working after changing a Scope?

Revert the changes, or temporarily assign the API v2 full-access Scope to determine if the issue is permissions-related.

Knowledge Base

💡Knowledge Base Home | 🚀What's New | 📅Upcoming Training Events