overlay: 1.0.0 info: title: API Evangelist enhancements for the Kinde Management API version: 1.0.0 x-generated: '2026-09-12' x-method: generated x-source: >- Generated from artifacts already in this repo — scopes/kinde-scopes.yml (the published scope reference the contract omits), rate-limits/kinde-rate-limits.yml, conventions/kinde-conventions.yml and errors/kinde-problem-types.yml — plus probed discovery documents. Every value it writes is sourced from Kinde's own documentation; nothing is invented. x-extends: openapi/_original/kinde-management-api-openapi.yml x-also-applies-to: >- The 30 per-tag OpenAPIs under openapi/ are splits of this same source spec, so these actions apply to them equally where the targeted node is present. x-rationale: >- The Kinde Management API's largest machine-readability gap is that its documented OAuth scope model does not appear in the contract at all. 168 of 169 operations declare a 403 and the spec never says which scope avoids it. This overlay records what Kinde publishes in prose, without mutating the original spec. actions: - target: $.info description: Record the documented runtime semantics the contract itself does not carry. update: x-rate-limit: status: 429 declared-on-every-operation: true response-headers: [RateLimit-Reset] headers-not-returned: [RateLimit-Limit, RateLimit-Remaining, Retry-After] page-size-max: 500 bulk-objects-max: 100 limiters: [rate, concurrency] threshold-published: false docs: https://docs.kinde.com/developer-tools/kinde-api/api-rate-limits/ x-idempotency: supported: false coverage: none note: >- No Idempotency-Key header or replay protection is documented anywhere. Callers are told to retry 429s, so a lost create response can duplicate a record. x-pagination: style: opaque-cursor request: [page_size, next_token] response: [next_token] page-size-max: 500 x-error-format: rfc9457: false media-types: [application/json, 'application/json; charset=utf-8'] envelope: '{errors:[{code,message}]}' catalog: errors/kinde-problem-types.yml x-versioning: scheme: path current: v1 deprecation-policy-published: false sunset-header: false x-reversibility: grade: documented note: >- Deletes are permanent with no published retention window. Prefer updateUser with is_suspended over deleteUser. Detail in conventions/kinde-conventions.yml. x-tenancy: model: subdomain-per-tenant base: https://{subdomain}.kinde.com note: >- Environments are separate tenants. An org_code or user id from development does not resolve in production; that mismatch is the most common cause of an unexpected 404. - target: $.components.securitySchemes description: >- Record the OAuth 2.0 client-credentials flow and the published scope catalogue. The spec declares only an http/bearer scheme, so the scope model is invisible to generated SDKs. update: x-kindeOAuth2Documented: type: oauth2 x-note: >- DOCUMENTED, NOT DECLARED. Kinde's published contract carries only kindeBearerAuth (http/bearer). This node records the flow and scopes exactly as documented at https://docs.kinde.com/developer-tools/kinde-api/api-scopes/ so that tooling can see them. It does not assert that the provider declares an oauth2 scheme. flows: clientCredentials: tokenUrl: https://{subdomain}.kinde.com/oauth2/token x-audience-required: https://{subdomain}.kinde.com/api x-scope-narrowing: >- Pass a space-delimited scope parameter in the token request body to issue a token with fewer scopes than the M2M application holds. scopes: 'read:users': Read user details 'create:users': Create users 'update:users': Update user details 'delete:users': Delete users 'read:user_identities': Read linked identity providers for a user 'read:organizations': Read organizations 'create:organizations': Create organizations 'update:organizations': Update organizations 'delete:organizations': Delete organizations 'read:organization_users': Read users in an organization 'create:organization_users': Add users to an organization 'update:organization_users': Update organization user details 'delete:organization_users': Remove users from an organization 'read:roles': Read roles 'create:roles': Create roles 'update:roles': Update roles 'delete:roles': Delete roles 'read:organization_user_roles': Read roles assigned to organization users 'create:organization_user_roles': Assign roles to organization users 'delete:organization_user_roles': Remove roles from organization users 'read:role_permissions': Read the permissions attached to a role 'read:permissions': Read permissions 'create:permissions': Create permissions 'update:permissions': Update permissions 'delete:permissions': Delete permissions 'read:applications': Read application details 'create:applications': Create applications 'update:applications': Update application details 'delete:applications': Delete applications 'read:feature_flags': Read feature flags 'create:feature_flags': Create feature flags 'update:feature_flags': Update feature flags 'delete:feature_flags': Delete feature flags 'read:environments': Read environment details 'update:environments': Update environment settings 'read:environment_variables': Read environment variables 'create:environment_variables': Create environment variables 'update:environment_variables': Update environment variables 'delete:environment_variables': Delete environment variables 'read:connections': Read connection details 'create:connections': Create connections 'update:connections': Update connections 'delete:connections': Delete connections 'read:webhooks': Read webhooks 'create:webhooks': Create webhooks 'update:webhooks': Update webhooks 'delete:webhooks': Delete webhooks 'read:properties': Read custom properties 'create:properties': Create custom properties 'read:subscribers': Read subscribers 'create:subscribers': Create subscribers 'read:apis': View MCP connections, tools and audit 'update:apis': Create, delete and authorize APIs; configure backend auth - target: $.paths..[?(@.operationId)] description: >- Flag every operation reachable through the Kinde MCP server. 22 of 169 are; the MCP server is granted no update or delete scopes at all. update: x-mcp-reachable-see: mcp/kinde-tool-crosswalk.yml - target: $.info description: Point at the derived artifacts that carry the rest of this profile. update: x-apievangelist-artifacts: conventions: conventions/kinde-conventions.yml errors: errors/kinde-problem-types.yml scopes: scopes/kinde-scopes.yml rate-limits: rate-limits/kinde-rate-limits.yml lifecycle: lifecycle/kinde-lifecycle.yml conformance: conformance/kinde-conformance.yml data-model: data-model/kinde-data-model.yml tool-crosswalk: mcp/kinde-tool-crosswalk.yml webhooks: webhooks/kinde-webhooks.yml skills: skills/_index.yml