Secure your API using scopes

You must be on the Kinde Plus plan and higher to use custom API scopes.

Kinde lets you add custom scopes to help manage 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 > Environment > 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.

Import scopes from an OpenAPI spec

Link to this section

If your API is already described in an OpenAPI 3.x or Swagger 2 specification, you can upload the file to Kinde and automatically generate scopes from your API operations — instead of adding each scope manually.

You need a registered custom API (not the Kinde Management API) and the API scopes feature enabled for your plan.

Upload an OpenAPI spec

Link to this section

1. In Kinde, go to Settings > Environment > APIs.
2. Select View details on the API you want to generate scopes for.
3. In the side menu, select OpenAPI spec.
4. Select Upload file.
5. Choose a .json, .yaml, or .yml file that contains a valid OpenAPI 3.x or Swagger 2 document with a paths object. (Maximum file size: 20MB) Your file will be uploaded.

Kinde parses the file and creates one scope per supported HTTP operation in the spec. When the import finishes, the generated scopes appear on the Scopes tab. Scopes imported from OpenAPI are labeled with an OpenAPI badge.

How scopes are generated

Link to this section

Kinde creates a scope for each HTTP operation (GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD, and TRACE) defined under paths in your spec.

Each scope name follows this pattern:

{method}:{normalized_path}

For example, these operations:

OpenAPI path	HTTP method	Generated scope
/users/{userId}	GET	get:users_userid
/users/{userId}	POST	post:users_userid
/health	GET	get:health

Kinde builds the scope name by:

• Lowercasing the HTTP method and path
• Removing { and } from path parameters (for example, {userId} becomes userid)
• Replacing non-alphanumeric characters with underscores
• Replacing / with _

If a generated scope name would exceed 64 characters, Kinde shortens it and appends a stable hash suffix so scope names stay unique.

The scope description is taken from the operation’s summary field when present. If there is no summary, Kinde uses operationId, or falls back to the HTTP method and path (for example, GET /users/{userId}).

Reserved scope names (such as openid, profile, and offline_access) are skipped and not imported.

Manage imports

Link to this section

After your first upload, the OpenAPI spec page shows:

• Active file — the currently active spec and when it was uploaded
• Import history — previous uploads and deletions

Select View logs on any history entry to see a report of scopes that were created, skipped as duplicates, or removed during that import.

Upload a new spec

Link to this section

To sync scopes with an updated API definition, upload a new file from the OpenAPI spec page.

When you upload a replacement file:

• New operations in the spec create new scopes
• Operations that already have a matching scope are reported as duplicates and are not recreated
• Scopes that were generated from the previous import but are no longer in the new spec are removed

You need permission to delete API scopes to replace an existing import.

Delete an import

Link to this section

To remove an OpenAPI import and all scopes generated from it:

1. On the OpenAPI spec page, open the actions menu on the active file row.
2. Select Delete import.
3. Confirm the deletion.

This removes only scopes that were generated from that import. Scopes you added manually on the Scopes tab are not affected.

Work with generated scopes

Link to this section

Generated scopes behave like manually created scopes. You can authorize them for applications, assign them to API keys, and request them in token calls.

On the Scopes tab, scopes imported from OpenAPI show an OpenAPI badge. You cannot edit or delete individual generated scopes from the Scopes tab — update them by uploading a new spec, or remove them by deleting the import on the OpenAPI spec page.

Permissions required

Link to this section

Action	Permissions
View the OpenAPI spec page	read:apis
Upload a spec (first import)	create:api_scopes, update:apis
Replace an existing import	create:api_scopes, update:apis, delete:api_scopes
Delete an import	update:apis, delete:api_scopes

Authorize and enable scopes for an application

Link to this section

1. Go to Settings > Environment > 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 > Environment > 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 on who has the keys.