Scopes play a crucial role in securing and controlling access to specific functionalities within our API.

You can think of them as the permissions each API key has to access data.

In this guide, we'll delve into what scopes are, why they are used, and how you can effectively manage them to tailor your application's access.

What are scopes?

Scopes define the specific permissions or actions that an API key is allowed to perform. Each scope corresponds to a set of functionalities or resources within the API. By associating scopes with your API key, you can fine-tune the level of access your application has.

Without specifying any scope, you won't be able to utilise the API.

Included scopes

Each set of API keys only provides access to one Mention Me Merchant. This is automatically enforced when you setup your credentials.

They also only allow access to one environment.

If you need access to multiple Merchants, e.g. Brand A and Brand B, you will need different API keys.

Equally, if you require access to multiple environments, e.g. demo.mention-me.com and mention-me.com, you will also need different API keys.

Scopes you can choose

Each API defined in our reference explains which scope(s) are required to use that API.

For example, if you want to create a new customer, you'll need to grant the customer:write scope.

Each scope is suffixed with the level of privilege it grants for a particular type of collection, with three levels available:

• :read - allows you to read an item in a collection
• :write - allows you to create or update an existing item in a collection
• :delete - allows you to delete an existing item in a collection

NB: Not all collections provide all levels.

Least privilege

We recommend following the principle of least privilege. This means to provide each set of credentials as little access as possible required to do what is required.

E.g. we recommend for a customer service application is only given :read access, whereas a tool for updating data might only be given :write - i.e. each application has the minimal permissions required.