ApiScope

Defines granular permissions and access boundaries for API authentication, specifying actions allowed on resources. Supports hierarchical scope relationships with parent-child inheritance and lifecycle management for safe permission evolution. Applicable across SaaS platforms, microservices, and API management systems requiring fine-grained access control.

13 properties

Schema

Properties

Property	Type	Mode	Description	Required
name	string	stored	Unique identifier for the scope following a namespaced convention, typically using colon-separated segments like 'resource:action' or wildcard patterns for broader permissions Example: `"read:users"`	Required
displayName	string	stored	Human-readable name for the scope that clearly communicates its purpose to administrators and developers reviewing API key permissions Example: `"Read User Profiles"`	Required
description	string	stored	Comprehensive explanation of what access rights and capabilities this scope grants, including specific resources, operations, and any limitations or special conditions Example: `"Grants read-only access to user profile information including names, email addresses, and basic metadata. Does not include sensitive fields like passwords or payment information."`	Required
category	string	stored	Organizational grouping that categorizes the scope by resource domain or functional area, facilitating scope discovery and management in user interfaces Example: `"users"`	Required
resource	KernelModel	stored	Optional reference to a specific data model or entity type that this scope controls access to, enabling entity-specific permission enforcement Example: `"User"`	Optional
actions	string[]	stored	Array of permitted operation types that this scope authorizes, using standardized action verbs to define the scope of access control Example: `["read","list"]`	Required
isSystem	boolean	stored	Indicates whether this scope is part of the core system-defined permission set and protected from modification or deletion by administrators Example: `true`	Required
isDefault	boolean	stored	Specifies whether this scope should be automatically included when creating new API keys or tokens, typically used for safe, read-only base permissions	Required
status	string	stored	Current lifecycle state of the scope determining its availability and behavior in the authorization system Values: `active, deprecated, disabled` Example: `"active"`	Required
parentScope	ApiScope	stored	Reference to a parent scope in hierarchical permission structures, where child scopes are implicitly included when the parent scope is granted	Optional
metadata	json	stored	Extensible key-value storage for additional scope attributes, custom properties, integration mappings, or platform-specific configuration data Example: `{"rateLimitMultiplier":1,"auditLevel":"standard"}`	Optional
childScopesCount	number	calculated	Calculated count of child scopes that reference this scope as their parent, useful for understanding permission hierarchy depth and breadth Example: `3`	Optional
apiKeysCount	number	calculated	Calculated count of active API keys currently assigned this scope, providing visibility into scope utilization and impact assessment for changes Example: `127`	Optional

Examples

Example 1

{
  "@type": "ApiScope",
  "name": "read:users",
  "displayName": "Read User Profiles",
  "description": "Grants read-only access to user profile information including names, email addresses, and basic metadata. Does not include sensitive fields like passwords or payment information.",
  "category": "users",
  "resource": null,
  "actions": [
    "read",
    "list"
  ],
  "isSystem": true,
  "isDefault": false,
  "status": "active",
  "parentScope": null,
  "metadata": {
    "rateLimitMultiplier": 1,
    "auditLevel": "standard"
  },
  "childScopesCount": 0,
  "apiKeysCount": 247
}

Example 2

{
  "@type": "ApiScope",
  "name": "write:documents",
  "displayName": "Create and Update Documents",
  "description": "Allows creating new documents and updating existing documents owned by the authenticated user or shared with appropriate permissions. Does not grant deletion rights or admin-level document management.",
  "category": "documents",
  "resource": null,
  "actions": [
    "create",
    "update",
    "read"
  ],
  "isSystem": true,
  "isDefault": false,
  "status": "active",
  "parentScope": null,
  "metadata": {
    "rateLimitMultiplier": 2,
    "auditLevel": "detailed",
    "requiresOwnership": true
  },
  "childScopesCount": 0,
  "apiKeysCount": 89
}

Example 3

{
  "@type": "ApiScope",
  "name": "admin:*",
  "displayName": "Full Administrative Access",
  "description": "Grants unrestricted access to all system resources and operations including user management, system configuration, billing, and data deletion. This is a privileged scope that should only be assigned to trusted administrative applications and services.",
  "category": "admin",
  "resource": null,
  "actions": [
    "*"
  ],
  "isSystem": true,
  "isDefault": false,
  "status": "active",
  "parentScope": null,
  "metadata": {
    "rateLimitMultiplier": 5,
    "auditLevel": "comprehensive",
    "requiresMFA": true,
    "alertOnUse": true
  },
  "childScopesCount": 8,
  "apiKeysCount": 5
}

Example 4

{
  "@type": "ApiScope",
  "name": "read:orders",
  "displayName": "Read Order Data",
  "description": "Provides read access to order records including order details, items, pricing, and fulfillment status. This scope is linked to the Order entity model for granular entity-level permission enforcement.",
  "category": "orders",
  "resource": "Order",
  "actions": [
    "read",
    "list"
  ],
  "isSystem": true,
  "isDefault": false,
  "status": "active",
  "parentScope": null,
  "metadata": {
    "rateLimitMultiplier": 1.5,
    "auditLevel": "standard",
    "dataClassification": "confidential"
  },
  "childScopesCount": 0,
  "apiKeysCount": 156
}

Example 5

{
  "@type": "ApiScope",
  "name": "legacy:write:products",
  "displayName": "Legacy Product Write Access",
  "description": "Deprecated scope previously used for product catalog management. New implementations should use 'write:catalog' instead which provides enhanced granularity and better permission controls.",
  "category": "products",
  "resource": null,
  "actions": [
    "create",
    "update",
    "delete"
  ],
  "isSystem": true,
  "isDefault": false,
  "status": "deprecated",
  "parentScope": null,
  "metadata": {
    "deprecatedDate": "2024-06-15",
    "replacementScope": "write:catalog",
    "sunsetDate": "2025-12-31",
    "migrationGuideUrl": "https://docs.example.com/scope-migration"
  },
  "childScopesCount": 0,
  "apiKeysCount": 23
}

Example 6

{
  "@type": "ApiScope",
  "name": "admin:read",
  "displayName": "Administrative Read Access",
  "description": "Provides read-only access to administrative resources and system configuration data without modification rights. This scope is a child of admin:* and is automatically granted when the parent scope is assigned.",
  "category": "admin",
  "resource": null,
  "actions": [
    "read",
    "list"
  ],
  "isSystem": true,
  "isDefault": false,
  "status": "active",
  "parentScope": "admin:*",
  "metadata": {
    "rateLimitMultiplier": 2,
    "auditLevel": "detailed",
    "allowDashboardAccess": true
  },
  "childScopesCount": 0,
  "apiKeysCount": 34
}

Example 7

{
  "@type": "ApiScope",
  "name": "execute:webhooks",
  "displayName": "Trigger Webhooks",
  "description": "Allows programmatic triggering of webhook events and management of webhook subscriptions. This scope is designed for integration platforms and automation tools that need to orchestrate event-driven workflows.",
  "category": "integrations",
  "resource": null,
  "actions": [
    "execute",
    "create",
    "read"
  ],
  "isSystem": true,
  "isDefault": false,
  "status": "active",
  "parentScope": null,
  "metadata": {
    "rateLimitMultiplier": 3,
    "auditLevel": "comprehensive",
    "requiresWebhookVerification": true,
    "maxConcurrentExecutions": 10
  },
  "childScopesCount": 0,
  "apiKeysCount": 67
}