Secure your API using scopes

You must be on the Kinde Plus or Scale plan to use this feature.

Kinde lets you add custom scopes to help manage others who access to your APIs. Scopes define token permissions used by your APIs, and provide a reliable way to control access to your API resources.

You need to have registered your APIs in Kinde to secure them using scopes.

Note that this topic is NOT about adding custom scopes for the Kinde Management API, it is only related to adding custom scopes to your own APIs. For information about Kinde Management API scopes, see this topic.

Benefits of using scopes

Link to this section

• Granular control: Instead of broad permissions like read or write, you can create scopes tailored to different levels of access, such as read:userprofile or write:roles.
• Security: You only need to grant the permissions necessary for each operation, minimizing the risk of unauthorized access to sensitive data or actions within your system.
• Flexibility: As your application grows and requirements change, you can easily add, remove, or modify scopes without affecting other parts of your system.
• Better UX: They simplify the authorization process and improve overall user experience.
• Compliance: They help you align with regulatory requirements or industry standards by ensuring that access to sensitive data is properly managed and audited.

Add scopes to an API

Link to this section

1. In Kinde, go to Settings > APIs.
2. Select View details on the API you want to add scopes for.
3. In the menu, select Scopes.
4. Select Add scope.
5. In the Add scope window, enter a name for the scope. This will be the name you use in your code to recognize the scope. We recommend following a consistent naming convention, such as read:user_status or write:mobilephone.
6. Add a description that explains what the scope is for and what it does.
7. Select Save.
8. Repeat from step 4 for all the scopes you want to add for this API.
9. Repeat from step 1 to add scopes for a different API.

Authorize and enable scopes for an application

Link to this section

1. Go to Settings > Applications and select View details on the relevant application.
2. Select APIs in the side menu.
3. If the application is not yet authorized, select the three dots menu next to the API you’re giving the app access to, and then select Authorize application.
4. In the same three dots menu, select Manage scopes.
5. In the window that opens, switch on or off the scopes allowed for the application.
6. Select Save.

Edit and delete scopes

Link to this section

Take care deleting scopes. If a scope is in use, it can cause breaking changes for users and applications that are dependent on them.

1. Go to Settings > APIs and select View details on the relevant API tile.
2. Select Scopes in the menu.
3. Find the scope you want to change.
4. Select the dots menu (far right) and select:
   • Edit scope. You can only change the scope description. Select Save.
   • Delete scope. Confirm that you want to delete and select Delete scope.

Request a subset of scopes for an authorized application

Link to this section

By default token requests for an authorized application will return all the scopes enabled in the section above. However, you can also optionally ask for a subset of enabled scopes to be returned by including them in the body of the access token request. You might do this to add more security to access requests for your API, or because you want your users to be very specific in their requests.

Example request

curl --request POST \
  --url 'https://<your_subdomain>.kinde.com/oauth2/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'client_id=<your_m2m_client_id>' \
  --data 'client_secret=<your_m2m_client_secret>' \
  --data 'audience=<your_api_audience>\
  --data 'scope=join:competitions update:competitions'

API Key scopes

Link to this section

If you manage access to your APIs using API keys, you can set scopes for the API keys, giving you more granular control over access, depending who has the keys.