Scopes for API keys

Scopes define what permissions an API key has when making requests to your API. You can create and define custom scopes when you register your API in Kinde, then assign them for each API key you create.

This topic is about strategies and considerations when assigning scopes to API keys.

Example custom scopes

Link to this section

The scopes you set will be related to what your app is and does. These are just some examples for AI apps.

• read:ai_chats
• write:ai_chat
• read:ai_analytics
• write:ai_analytics
• read:ai_workflows

Scope configuration

Link to this section

When creating an API key

Link to this section

1. Select the minimum required scopes for your use case.
2. Consider the principle of least privilege.
3. Review scope descriptions carefully.

MCP connections

Link to this section

When a user API key is used with an MCP connection, each selected scope maps to one MCP tool. Tools without a matching scope are hidden from the MCP client.

Grant only the scopes needed for the AI workflow. Because API keys are immutable, create a new key with updated scopes if you need to change which tools are available.

Updating existing API keys

Link to this section

API keys are immutable, so you can’t update the scopes of an existing API key. You can only create a new API key with the desired scopes.

Recommendations for API scopes best practice

Link to this section

Security

Link to this section

• Principle of least privilege: Only grant the minimum required scopes.
• Regular review: Periodically review and audit scope assignments.
• Scope isolation: Use different API keys for different purposes.

Structure

Link to this section

• Naming conventions: Use clear, descriptive scope names.
• Documentation: Document what each scope provides access to.
• Versioning: Consider scope versioning for breaking changes.

Scope validation

Link to this section

When your application receives a token, validate that it has the required scopes:

function hasRequiredScope(scopes, requiredScope) {
  return Array.isArray(scopes) && scopes.includes(requiredScope);
}

// Example usage (after verifying the API key)
if (!hasRequiredScope(verification.scopes, "write:users")) {
  return res.status(403).json({ error: "Insufficient scope" });
}