Scopes and Rate Limits

Production - PATCH /api/v1/api-keys/{keyId}/scopes, /rate-limit

API key scopes define what operations a key can perform, and rate limits control how frequently the key can be used.

6.6.4Available Scopes

curl -X GET http://localhost:8081/api/v1/api-keys/scopes \
  -H "Authorization: Bearer <access-token>"

Returns all available scopes with descriptions. Scopes follow the resource:action pattern.

Update Scopes

curl -X PATCH http://localhost:8081/api/v1/api-keys/15/scopes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{ "scopes": ["queries:execute", "catalog:read", "dashboards:read"] }'

Scope Validation

The ApiKey.hasScope() method supports exact match and wildcard patterns:

public boolean hasScope(String scope) {
    Set<String> scopeSet = getScopeSet();
    // Exact match or global wildcard
    if (scopeSet.contains("*") || scopeSet.contains(scope)) return true;
    // Prefix wildcard (e.g., "query:*" matches "query:read")
    String[] parts = scope.split(":");
    if (parts.length > 1) {
        return scopeSet.contains(parts[0] + ":*");
    }
    return false;
}

6.6.5Rate Limiting

curl -X PATCH http://localhost:8081/api/v1/api-keys/15/rate-limit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{ "rateLimit": 500 }'

Value	Meaning
`0`	Unlimited (no rate limit)
`> 0`	Maximum requests per minute

Expiring Keys

Get keys nearing expiration:

curl -X GET http://localhost:8081/api/v1/api-keys/expiring \
  -H "Authorization: Bearer <admin-token>"

Requires ADMIN role or api_keys:admin authority.

Key Rotation IP Whitelisting