Webhooks documentation for connected accounts and users

[saif-at-scalekit]

• Standardized the formatting of tags in the API schema for connected accounts and user endpoints to improve consistency and readability.
• Added a new query parameter for filtering permissions by type in the permissions endpoint.
• Introduced a new endpoint to retrieve the support email hash for the current logged-in user.
• Removed the deprecated endpoint for retrieving the authenticated user details.

These changes enhance the clarity and maintainability of the Scalekit API documentation.

Summary by CodeRabbit

New Features

• Added support hash retrieval endpoint for enhanced user support workflows
• Introduced connected accounts management capabilities (create, read, update, delete operations)
• Added domain management endpoints with improved domain-type semantics
• Enhanced session responses with authenticated client information
• Expanded organization membership data with detailed permission listings and permission type distinctions
• Introduced new permission and connector status enums for improved data modeling

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated the OpenAPI specification to introduce new endpoints for support hash retrieval and connected accounts management, along with expanded schemas for domains, permissions, and authenticated clients. Added new enums for connector types and permission classification while enriching session and organizational membership data structures with additional metadata fields.

Changes

Cohort / File(s)

Summary

API Specification and Schemas public/api/scalekit.scalar.json

Added new endpoints (/api/v1/users/support-hash, /api/v1/connected_accounts/*, /api/v1/domains/*, /api/v1/organizations/{organization_id}/domains). Introduced new schemas (usersGetSupportHashResponse, connected_accountsGetConnectedAccountByIdentifierResponse, sessionsAuthenticatedClients). Added enums (rolesPermissionType, connected_accountsConnectorStatus, connected_accountsConnectorType). Extended existing schemas with new fields: permissions in commonsOrganizationMembership, authenticated_clients in session and user contexts, and domain-type references across multiple endpoint definitions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Hops of joy through API land,
New endpoints bloom, so grand!
Connected accounts dance in line,
Domains gleam with types so fine,
Support hashes and sessions bright,
Our spec expands with pure delight! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title mentions 'Webhooks documentation' but the actual changes involve API schema updates, new endpoints, and permission structures with no webhook-related modifications evident in the summary.	Update the title to accurately reflect the main changes, such as 'Add support hash endpoint and connected accounts API schema' or 'Expand API schema with permissions and connected accounts endpoints'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch webhooks-connected-accounts

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[netlify]

✅ Deploy Preview for scalekit-starlight ready!

Name	Link
🔨 Latest commit	2263081
🔍 Latest deploy log	https://app.netlify.com/projects/scalekit-starlight/deploys/698ab954111fa400088136f2
😎 Deploy Preview	https://deploy-preview-424--scalekit-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@public/api/scalekit.scalar.json`:
- Around line 3451-3457: The OpenAPI entry for the query parameter named "type"
is inconsistent: its schema.enum only allows "SCALEKIT" and "ENVIRONMENT" but
the description references "ALL"; fix by aligning them — either add "ALL" to the
schema.enum and set the default to "ALL" (update the "schema" object to
["ALL","SCALEKIT","ENVIRONMENT"] and add "default":"ALL") or modify the
description to say "omit to return all" and remove the default reference; update
the "schema", "enum", and "description" fields for the parameter named "type"
accordingly.
- Around line 11751-12046: The ScalekitEvent schema currently restricts the
"type" and "object" enums and is missing the new connected_account events;
update components.schemas.ScalekitEvent to include the connected_account.*
values in the "type" enum (e.g. connected_account.created,
connected_account.updated, connected_account.deleted,
connected_account.magic_link_generated, connected_account.oauth_tokens_fetched,
connected_account.token_refresh_succeeded,
connected_account.token_refresh_failed, connected_account.oauth_succeeded) and
add "ConnectedAccount" to the "object" enum so the examples using type:
connected_account.* and object: ConnectedAccount validate correctly; locate the
ScalekitEvent definition and extend those enum lists accordingly.

📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9b862f5 and 2263081.

📒 Files selected for processing (2)

• public/api/scalekit.scalar.json
• public/api/scalekit.scalar.yaml

🧰 Additional context used

📓 Path-based instructions (1)

**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy,gradle,xml,json}

📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)

Comments should not duplicate the code - avoid comments that simply restate what the code does; comments should add value beyond what's obvious from reading the code

Files:

• public/api/scalekit.scalar.json

🧠 Learnings (3)

📚 Learning: 2026-02-02T05:55:51.251Z

Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:72-179
Timestamp: 2026-02-02T05:55:51.251Z
Learning: In the `src/content/docs/authenticate/fsa/multiapp/` directory, the multi-app authentication documentation (native-app.mdx, single-page-app.mdx, web-app.mdx, overview.mdx) currently uses conceptual shell/curl examples instead of multi-language SDK code examples because the Scalekit SDKs have not yet been built/updated for multi-app functionality. Once the SDKs are ready, these files should be updated to include all 4 languages (Node.js, Python, Go, Java) using `<Tabs syncKey="tech-stack">`.

Applied to files:

• public/api/scalekit.scalar.json

📚 Learning: 2026-01-13T12:47:04.673Z

Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-13T12:47:04.673Z
Learning: Applies to **/*.{js,ts,py,go,java,tsx,jsx} : SDK variable names must follow language-specific conventions: Node.js uses `scalekit`, Python uses `scalekit_client`, Go uses `scalekitClient`, Java uses `scalekitClient`

Applied to files:

• public/api/scalekit.scalar.json

📚 Learning: 2026-01-13T12:46:55.260Z

Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use consistent SDK variable naming: Node.js='scalekit', Python='scalekit_client', Go='scalekitClient', Java='scalekitClient'

Applied to files:

• public/api/scalekit.scalar.json

🔇 Additional comments (4)

public/api/scalekit.scalar.json (4)

2733-2790: Domain-type guidance is now consistent across endpoints.

The clarified semantics across list/create/get/delete plus the tag docs make the SSO routing vs allowed email domain behavior much easier to reason about.

Also applies to: 2819-2854, 2893-2954, 5190-5191, 7744-7746, 9579-9585

---

4647-4666: Support-hash endpoint addition looks good.

Clear, minimal response shape for the current user and consistent naming.

Also applies to: 9160-9166

---

5986-5993: Permission provenance + error context additions are solid.

Exposing effective permissions, a permission type/provenance flag, and required permissions in errors improves auditability and troubleshooting.

Also applies to: 7869-7875, 8492-8509

---

8669-8684: Session authenticated‑client metadata is a useful audit addition.

The client/organization context should help debugging cross‑client sessions without changing existing fields.

Also applies to: 8830-8837

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}