docs: add API keys (opaque tokens) documentation#446
Conversation
Add comprehensive documentation for opaque API tokens under "Add auth to your APIs" section. Covers create, validate, list, and invalidate operations with code examples in all 4 SDKs (Node.js, Python, Go, Java). Includes middleware patterns for protecting API endpoints and best practices. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add tags, error handling, security comments, collapse for init blocks, Python tuple explanation, and closing next-steps section.
… improvements - Rename opaque-tokens.mdx to api-keys.mdx, update sidebar config - Rewrite intro with Scalekit recommendation tone - Add D2 sequence diagram showing API key lifecycle flow - Split create token into org-scoped and user-scoped subsections - Add validate subsections for roles/externalOrgId and custom metadata - Reorder invalidate examples (API key first, tokenId second) - Remove framework titles from generic code examples - Replace log.Fatalf with log.Printf in Go examples - Update all prose references from opaque tokens to API keys
Update all validate token examples to catch SDK-specific exceptions (ScalekitValidateTokenFailureException, ErrTokenValidationFailed, TokenInvalidException) instead of generic Error/Exception, and add bullet-pointed intro section.
Rewrite prose sections with a warmer, more conversational tone matching the api-auth-quickstart and scopes articles. Move API keys to last position under "Add auth to your APIs" in the sidebar.
…nology and enhance clarity - Changed the title from "Add auth to your APIs" to "Add OAuth2.0 to your APIs" for specificity. - Revised introductory content to clarify the role of APIs and the importance of OAuth 2.0 for client credentials authentication. - Improved the description of the API client registration process, emphasizing customer interaction and Scalekit integration. - Added details on API client scopes and their validation, enhancing security context. - Included collapsible sections for sample responses to improve readability and organization. This update aligns the documentation with current standards and enhances user understanding of OAuth 2.0 integration.
…ters for Go optional proto fields, add missing Token import in Java middleware
… error handling to list/invalidate examples across all languages
Python SDK's token.py dropped .with_call so methods now return plain proto response objects instead of (response, call) tuples. Update all Python code examples in the API keys guide to remove [0] indexing.
hrishikesh-p
requested review from
amitash1912,
ravibits and
saif-at-scalekit
as code owners
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughConsolidates M2M authentication docs into authenticate/m2m (OAuth 2.0 client‑credentials and API keys), removes the legacy scopes guide, updates sidebar and redirects for backward compatibility, and adds documentation/editorial rules in CLAUDE.md. No runtime code or public API changes. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx (3)
58-58:⚠️ Potential issue | 🟠 MajorReplace hardcoded docs URL with a root-relative internal link.
This points to
https://docs.scalekit.com/...; use a root-relative path so links remain environment-agnostic.
As per coding guidelines, "Internal links MUST use root-relative paths ... Flag any hardcodedhttps://docs.scalekit.comlinks".🔗 Suggested fix
- Alternatively, you can use the <a href="https://docs.scalekit.com/apis/#tag/api-auth" target="_blank" rel="noopener">REST APIs directly</a>. + Alternatively, you can use [REST APIs directly](/apis/#tag/api-auth).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx` at line 58, Replace the hardcoded external docs URL in the anchor that currently points to "https://docs.scalekit.com/apis/#tag/api-auth" (the link text "REST APIs directly") with a root-relative internal path (e.g., "/apis/#tag/api-auth") so the link is environment-agnostic; update the href attribute in the anchor tag accordingly and ensure target/rel attributes remain unchanged.
61-62:⚠️ Potential issue | 🟠 MajorSDK support note is inconsistent with the rest of this page.
Line 61 says only Python SDKs are supported, but later sections provide Node.js examples and the PR adds broader multi-SDK guidance. This creates trust and support confusion.
Based on learnings, "Keep documentation synchronized with product changes".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx` around lines 61 - 62, The "Currently Scalekit supports Python SDKs" note is inconsistent with Node.js examples later; update the inline SDK support sentence (the string "Currently Scalekit supports Python SDKs, <a href=\"/support/contact-us\">contact us</a> if you need support for your tech stack.") to accurately list supported SDKs (e.g., "Scalekit provides Python and Node.js SDKs; contact us for other languages") or to a generic statement that matches the rest of the doc, and verify examples in this file (the Node.js snippets) still align with the new note.
74-232:⚠️ Potential issue | 🟠 MajorStandardize tech-stack tabs and include all four SDK languages for SDK snippets.
Several SDK sections use partial language tabs and inconsistent tab values (
javascriptvsnode), which breaks synced-tab behavior and violates the docs standard.
As per coding guidelines, "ALL code examples that show SDK usage MUST include all four language tabs: Node.js, Python, Go, Java — using<Tabs syncKey="tech-stack">" and "Use consistent Tab labels ... with TabItem valuesnode/python/go/java".Also applies to: 244-270, 296-363, 552-672
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx` around lines 74 - 232, The Tabs block using syncKey="tech-stack" and its TabItem entries are inconsistent and missing SDK languages; update each SDK example (the Tabs with syncKey="tech-stack" and any TabItem entries currently labeled "curl", "javascript", or "node") to include four SDK TabItem entries with values and labels exactly: value="node" label="Node.js", value="python" label="Python", value="go" label="Go", and value="java" label="Java" (you may keep a separate non-synced "curl" example outside or separate tab if needed), ensure every section mentioned (the current Tabs block plus the ranges noted in the review) uses the same syncKey="tech-stack" and consistent TabItem values so synced-tab behavior works across all SDK snippets.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/configs/redirects.config.ts`:
- Around line 276-277: The redirect for '/m2m/scopes' currently points to
'/guides/m2m/scopes/' which then redirects to
'/authenticate/m2m/api-auth-quickstart/', causing a two‑hop redirect; update the
mapping so the '/m2m/scopes' key maps directly to
'/authenticate/m2m/api-auth-quickstart/' (and leave or remove the intermediate
'/guides/m2m/scopes/' -> '/authenticate/...' mapping as desired) by changing the
value for '/m2m/scopes' in redirects.config.ts.
In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx`:
- Around line 393-418: The sample response contains a realistic-looking
credential in the plain_secret field which can trigger secret scanners; update
the sample JSON in the "Sample response" block so the plain_secret value is
replaced with an obvious placeholder (e.g., "<REDACTED_SECRET>" or "REDACTED")
instead of the current secret-like string, leaving the surrounding keys (client,
secrets, etc.) unchanged; ensure you modify the plain_secret key in the sample
response so future commits don’t include real-looking credentials.
- Line 5: The frontmatter label "label: \"API authentication with M2M OAuth\""
is not action-oriented; update the label key value to follow the "Action +
Object" pattern (start with a verb) — e.g., replace the current value with
something like "Secure APIs with OAuth" (or another concise verb + object
phrase) to conform to BrowseCentral labeling guidelines; ensure you modify the
label field (the "label" string) in api-auth-quickstart.mdx accordingly.
- Around line 28-31: Fix grammar and phrasing in the intro and scope sentences:
change "it's data" to "its data", "OAuth2.0 based" to "OAuth 2.0-based", and
replace the malformed sentence "In should here's how it would work:" with a
clear simple sentence such as "Here's how it works:"; also correct "or example"
to "For example" near the later occurrence. Update the lines containing those
exact phrases so the copy reads simply and directly with short sentences and
plain language.
In `@src/content/docs/authenticate/m2m/api-keys.mdx`:
- Around line 674-696: The Java example for listing tokens only shows the
success path; wrap calls to scalekitClient.tokens().list (used for
ListTokensResponse and Token handling) in try-catch blocks and demonstrate error
handling: catch relevant exceptions (e.g., IOException/RuntimeException or the
client-specific exception), log or print an error message including
exception.getMessage(), and handle failures for the initial list, the paginated
nextPage call, and the filtered userTokens call so each invocation shows both
success and error paths.
- Around line 950-957: Add an explicit "what's next" pointer at the end of this
page by appending either a next: frontmatter link, a <LinkCard> component, or a
short paragraph directing readers to the recommended subsequent page in the
sidebar journey; specifically, update
src/content/docs/authenticate/m2m/api-keys.mdx to include a next: frontmatter
entry (e.g., next: /docs/authenticate/m2m/session-management) or insert a
<LinkCard> or one-line paragraph such as "What's next: [Title of next page] —
link" so the page ends with a clear navigation signal.
- Around line 21-23: Fix the opening paragraph grammar and terminology: change
"API keys gives you" to "API keys give you", normalize casing to "API keys"
throughout the paragraph (or choose singular "API key" consistently), convert
"User Level" to "user-level", break long sentences into shorter ones and
simplify wording in the two paragraphs that start "When your customers need to
integrate..." and "Unlike [JWT-based M2M authentication]..." so they use plain
language and consistent terms (e.g., "API keys do not carry embedded claims" ->
keep concise), ensuring each sentence is direct and terms like "organization",
"user", "API key(s)", "server-side validation", and "revocation" are used
consistently.
---
Outside diff comments:
In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx`:
- Line 58: Replace the hardcoded external docs URL in the anchor that currently
points to "https://docs.scalekit.com/apis/#tag/api-auth" (the link text "REST
APIs directly") with a root-relative internal path (e.g., "/apis/#tag/api-auth")
so the link is environment-agnostic; update the href attribute in the anchor tag
accordingly and ensure target/rel attributes remain unchanged.
- Around line 61-62: The "Currently Scalekit supports Python SDKs" note is
inconsistent with Node.js examples later; update the inline SDK support sentence
(the string "Currently Scalekit supports Python SDKs, <a
href=\"/support/contact-us\">contact us</a> if you need support for your tech
stack.") to accurately list supported SDKs (e.g., "Scalekit provides Python and
Node.js SDKs; contact us for other languages") or to a generic statement that
matches the rest of the doc, and verify examples in this file (the Node.js
snippets) still align with the new note.
- Around line 74-232: The Tabs block using syncKey="tech-stack" and its TabItem
entries are inconsistent and missing SDK languages; update each SDK example (the
Tabs with syncKey="tech-stack" and any TabItem entries currently labeled "curl",
"javascript", or "node") to include four SDK TabItem entries with values and
labels exactly: value="node" label="Node.js", value="python" label="Python",
value="go" label="Go", and value="java" label="Java" (you may keep a separate
non-synced "curl" example outside or separate tab if needed), ensure every
section mentioned (the current Tabs block plus the ranges noted in the review)
uses the same syncKey="tech-stack" and consistent TabItem values so synced-tab
behavior works across all SDK snippets.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
⛔ Files ignored due to path filters (1)
public/d2/docs/authenticate/m2m/api-keys-0.svgis excluded by!**/*.svg
📒 Files selected for processing (7)
CLAUDE.mdsrc/configs/redirects.config.tssrc/configs/sidebar.config.tssrc/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/guides/m2m/api-auth-m2m-clients.mdxsrc/content/docs/guides/m2m/scopes.mdx
💤 Files with no reviewable changes (2)
- src/content/docs/guides/m2m/scopes.mdx
- src/content/docs/guides/m2m/api-auth-m2m-clients.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (10)
**/*.{yml,yaml,md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/browsecentral-labels.mdc)
**/*.{yml,yaml,md,mdx}: BrowseCentral labels should be maximum 3-5 words - keep concise but add context when needed
BrowseCentral labels should be action-oriented - start with verbs when possible
BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
BrowseCentral labels should include specific context when needed (e.g., 'Configure Scalekit MCP server', 'Validate incoming API requests')
BrowseCentral labels should use integration context when applicable (e.g., 'Build MCP auth with your existing auth system')
BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'
Files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/deno-docs-style.mdc)
**/*.{md,mdx}: Use sentence case for all titles and headings in MD/MDX documentation
Keep page titles short and descriptive (3–7 words when possible) in MD/MDX documentation
Use outcome-focused headings that describe results, not categories (e.g., 'Run a script' not 'Scripts')
Avoid gerunds in headings when an imperative works - prefer 'Configure proxies' over 'Configuring proxies'
Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Use sentence case in sidebar labels without punctuation
Set frontmatter title in sentence case with a clear outcome; description in one sentence (≤160 chars); sidebar.label as shorter form of title; enable tableOfContents on longer pages
Start documentation pages with a one-paragraph overview explaining what the page covers and when to use it
Present the primary use case (80% path) first in documentation, with edge cases later
Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Break up long documentation sections with subheadings every 3–6 paragraphs
Use asides for important notes, tips, cautions, and references in documentation
Provide runnable, minimal code examples that work as-is in documentation
Prefer CLI-first examples and show file layout when helpful in documentation
Label code blocks with titles for context (e.g., 'Terminal', 'main.ts') in documentation
Keep code block annotations brief and purposeful - annotate only what matters
Use consistent variable and file names across a documentation page
Use descriptive link text in documentation (e.g., 'See permission flags' not 'click here')
Prefer relative links for internal documentation pages and include anchors for section references
Reference APIs consistently using backticks for code, file names, CLI flags, and endpoints
Use backticks for code, file names, CLI flags, and endpoints in documentation
Use lists for options and features in documentation; tables only when comparisons are cleare...
Files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
CLAUDE.md
⚙️ CodeRabbit configuration file
CLAUDE.md: CLAUDE.md is the quick-reference for AI assistant behavior in this repo.
- It MUST reference
.specify/memory/constitution.mdas the single
source of truth.- SDK variable names section is CRITICAL — any change here must be
intentional and reflected across all code examples in the docs.- The "Quality Checklist" section must end every AI-generated draft
withSTYLE-CHECK: [PASSED | TODO].
Files:
CLAUDE.md
**/*.{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:
src/configs/sidebar.config.tssrc/configs/redirects.config.ts
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}: Good comments do not excuse unclear code - refactor the code to be self-explanatory instead of using comments to explain poorly written code; use better variable names, function names, and code structure
Comments should dispel confusion, not cause it - ensure comments clarify rather than obscure the code's purpose; avoid cryptic or joke comments
Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Provide links to the original source of copied code - always attribute code copied from external sources with URLs to Stack Overflow answers, GitHub repositories, or documentation
Include links to external references where helpful - reference standards, RFCs, and official documentation; link to relevant specifications when implementing protocols
Add comments when fixing bugs - document bug fixes with context about the issue, reference issue trackers and bug reports, and explain workarounds and their limitations
Use comments to mark incomplete implementations - use standard formats for TODO, FIXME, and NOTE comments with context about what needs to be done and reference issue trackers when possible
Always document public APIs with function/class comments - explain the purpose, parameters, return values, and exceptions; include usage examples for complex functions
Include file headers with copyright information, license, and authorship - provide a brief description of the file's purpose and document dependencies and requirements
Files:
src/configs/sidebar.config.tssrc/configs/redirects.config.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Use JSDoc standards for all function, class, and complex logic comments in JavaScript/TypeScript - include parameter descriptions (
@param), return values (@returns), types (@type), and descriptions; document exceptions and edge cases
Files:
src/configs/sidebar.config.tssrc/configs/redirects.config.ts
src/configs/sidebar.config.ts
⚙️ CodeRabbit configuration file
src/configs/sidebar.config.ts: This file defines the user journey across ALL documentation sections.
When reviewing changes to this file:
- Verify that reordered items do not break the logical learning sequence
(e.g., "complete-login" must always come after "implement-login").- New items added to the FSA sidebar must follow the journey sequence:
Getting Started → User Auth → Auth Methods → Users & Orgs →
Authorization → Multi-App → APIs → Customize → Go Live.- Commented-out items (TODO) are acceptable but must include a comment
explaining WHY they are hidden.sidebarToSecondaryNavmappings MUST be updated whenever a new
sidebar section (id) is added.- External links MUST include the
attrsblock with
target: '_blank',rel: 'noopener noreferrer',class: 'external-link'.
Files:
src/configs/sidebar.config.ts
**/*.{ts,js,mjs}
⚙️ CodeRabbit configuration file
**/*.{ts,js,mjs}: Do NOT enforce code-commenting style rules on these files.
Specifically, do not flag:
- Comments that "duplicate" or restate what the code does.
- Missing comments on bug fixes, workarounds, or issue references.
- Missing inline documentation or explanatory comments.
Code comments are at the author's discretion.
Files:
src/configs/sidebar.config.tssrc/configs/redirects.config.ts
**/*.mdx
📄 CodeRabbit inference engine (.cursorrules)
**/*.mdx: Use clear, descriptive titles that explain the purpose of the document
Include comprehensive descriptions in frontmatter metadata
Organize content with logical heading hierarchy (H2, H3, H4)
Use tableOfContents property in frontmatter when content has multiple sections
Set appropriate sidebar labels for navigation in frontmatter
Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Use second person perspective ('your application', 'you receive', 'you must') in documentation
Keep sentences concise, aiming for under 25 words per sentence
Explain the 'why' in documentation with phrases like 'This prevents CSRF attacks by...' or 'Use this to validate that...'
Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Use future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Write 1-3 opening paragraphs that explain what users will accomplish, provide context about when/why, preview key concepts, and use direct instructional language
Begin introduction sections with a clear statement of what the guide covers and explain the problem being solved
Use collapsible sections in introduction for sequence diagrams, video demonstrations, data models, and JSON examples with appropriate icons
Use numbered format within Steps component:1. ## Titlewith all step content indented with exactly 3 spaces
Use action-oriented headings in step-by-step guides within Steps components
Include code examples in all 4 languages (Node.js, Python, Go, Java) within Steps co...
Files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
⚙️ CodeRabbit configuration file
**/*.mdx: You are reviewing Scalekit developer documentation written in MDX
(Astro + Starlight framework). Apply ALL of the following checks:Frontmatter
titleMUST be ≤ 60 characters and clearly state what the page does.descriptionMUST be ≤ 160 characters, action-oriented, unique per page.sidebar.labelMUST be present and ≤ 30 characters.sidebar.orderMUST be set on every page that lives inside a section
with siblings, to enforce the journey order in sidebar.config.ts.- Flag any missing
prev/nextlinks on pages that are clearly
part of a sequential flow (e.g., quickstart → implement-login →
complete-login → manage-session → logout).Voice & Style (CLAUDE.md standards)
- Voice: confident, direct, collaborative, instructional.
- Person: second person only ("you", "your application"). Reject "we",
"our", "the developer", "the user".- Tense: present tense for descriptions; imperative mood for instructions.
- Flag weasel words: "simply", "just", "easy", "straightforward",
"obviously", "of course", "note that".- Flag passive voice constructions where active voice is clearer.
- Headings must be sentence case, not Title Case (except proper nouns).
- No heading should end with a colon or period.
Content structure
- How-to guides MUST contain numbered
<Steps>(Starlight component).- Concept pages MUST NOT contain numbered steps — concepts explain, not instruct.
- API reference pages MUST list parameters in a table with Name / Type /
Required / Description columns.- Every page MUST end with a clear "what's next" signal — either a
next:frontmatter link, a<LinkCard>, or an explicit paragraph
pointing the reader forward in the sidebar journey.Code examples
- ALL code examples that show SDK usage MUST include all four language
tabs: Node.js, Python, Go, Java — using<Tabs syncKey="tech-stack">.- SDK variable names are STRICTLY:
scalekit(Node.js),
scalekit_client(Python),scalekitClient(Go), ...
Files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
src/content/docs/authenticate/**/*.mdx
⚙️ CodeRabbit configuration file
src/content/docs/authenticate/**/*.mdx: This page lives in the primary authentication section.
- If it's a quickstart or step-based guide, it MUST use
<Steps>.- Auth method pages (passwordless, social, SSO, passkeys) MUST include
a brief "when to use this" section before the implementation steps.- Any reference to tokens (idToken, accessToken, refreshToken) MUST
clarify: what it contains, its lifetime, and how to use it securely.- The FSA quickstart (
authenticate/fsa/quickstart.mdx) is the
canonical entry point — no other page should duplicate its 5-step
install→redirect→callback→session→logout structure.
Files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
🧠 Learnings (18)
📓 Common learnings
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
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">`.
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Keep documentation synchronized with product changes
Applied to files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-18T02:55:23.285Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-18T02:55:23.285Z
Learning: Applies to **/*.{md,mdx} : Use SDK variable names: Node.js `scalekit`, Python `scalekit_client`, Go `scalekitClient`, Java `scalekitClient`
Applied to files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 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:
CLAUDE.md
📚 Learning: 2026-02-10T05:32:59.967Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
Applied to files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Applied to files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-30T18:20:07.851Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:1-6
Timestamp: 2026-01-30T18:20:07.851Z
Learning: In the scalekit-inc/developer-docs repository, MDX files under `src/content/docs/authenticate/fsa/multiapp/` do not use `order` or `tags` fields in their frontmatter. Ordering and grouping are managed centrally in `src/configs/sidebar.config.ts`.
Applied to files:
src/configs/sidebar.config.tssrc/content/docs/authenticate/m2m/api-keys.mdx
📚 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:
src/configs/sidebar.config.tssrc/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 : Include configuration comments in code examples: '// Get the signing secret from Scalekit dashboard > Interceptors tab'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 : Include context comments explaining what's happening in code: '// Extract encrypted tokens from request cookies', '// Decrypt the access token before validation'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 : Always include security comments in security-related code with pattern: '// Security: ALWAYS verify requests are from Scalekit before processing'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-18T18:25:59.260Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 438
File: CONTRIBUTING.md:1-7
Timestamp: 2026-02-18T18:25:59.260Z
Learning: In scalekit-inc/developer-docs, root-level markdown files like CONTRIBUTING.md and README.md are standard GitHub repository files and do not require frontmatter. Only MDX files under src/content/docs/ that are processed by the Starlight docs system need frontmatter with title, description, and navigation metadata.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-30T18:18:50.883Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx:31-49
Timestamp: 2026-01-30T18:18:50.883Z
Learning: In all Scalekit documentation files (MDX), treat the terms 'Applications', 'Single Page Application (SPA)', 'Native Application', and 'Web Application' as proper nouns and preserve their capitalization in headings and body text. Ensure these terms remain capitalized even when used in sentence case or within prose.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-02-04T12:47:16.544Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 412
File: src/content/docs/dev-kit/tools/scalekit-dryrun.mdx:1-23
Timestamp: 2026-02-04T12:47:16.544Z
Learning: In scalekit-inc/developer-docs, the MDX frontmatter field order is required only when the sidebar configuration points to a directory (for auto-generation). If the sidebar.config.ts references a specific file path, the order field is not required. Apply this check to all MDX files under src/content/docs: if a file contributes to an auto-generated sidebar (directory path), ensure order is present; if it’s linked to a concrete file, order can be omitted. Use sidebar.config.ts to determine whether a given MDX file falls under directory-based vs file-specific sidebar references.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-02-25T08:57:12.201Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/quickstart.mdx:2-10
Timestamp: 2026-02-25T08:57:12.201Z
Learning: In Scalekit developer-docs (Astro Starlight), do not auto-suggest adding tableOfContents in frontmatter unless the user explicitly overrides the default behavior. The default enables tableOfContents with minHeadingLevel 2 and maxHeadingLevel 3. Only set tableOfContents when you want to customize heading levels or disable it entirely; otherwise omit it for other docs.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-02-25T03:34:41.147Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:31-31
Timestamp: 2026-02-25T03:34:41.147Z
Learning: In MDX files, import { Code } from 'astrojs/starlight/components' only if the MDX content actually uses the <Code> component. If the file uses only fenced code blocks (```), the import is not required. Apply this guideline to all MDX files (e.g., src/content/docs/**/*.mdx) to avoid unnecessary imports and reduce bundle size.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.mdx : Use Tabs/TabItem components for multi-language or multi-framework examples in MDX documentation
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 : Tabs components within Steps must be indented with 3 spaces, TabItem at same level as parent Tabs, code blocks properly indented within TabItem
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
🪛 Gitleaks (8.30.0)
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
[high] 417-417: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🪛 LanguageTool
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
[grammar] ~28-~28: Use a hyphen to join words.
Context: ... Scalekit provides a way to add OAuth2.0 based client credentials authentication ...
(QB_NEW_EN_HYPHEN)
[grammar] ~30-~30: Ensure spelling is correct
Context: ...thentication to your API endpoints. In should here's how it would work: ```d2 shape:...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (3)
CLAUDE.md (1)
20-23: Good addition to commit hygiene guidance.This is concise and fits the quick-reference intent of
CLAUDE.md.src/configs/sidebar.config.ts (1)
79-84: Navigation update looks correct.Adding
authenticate/m2m/api-keysdirectly after the M2M quickstart keeps the API-auth journey coherent.src/content/docs/authenticate/m2m/api-keys.mdx (1)
57-111: Great multi-language coverage across the token lifecycle.The create/validate/list/invalidate/protect sections are well-structured and consistently presented across Node.js, Python, Go, and Java.
Also applies to: 121-949
✅ Deploy Preview for scalekit-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
- redirects: collapse two-hop /m2m/scopes redirect to point directly to api-auth-quickstart - api-auth-quickstart: replace hardcoded docs.scalekit.com URL with root-relative path - api-auth-quickstart: update SDK support note to list all four SDKs (was Python-only) - api-auth-quickstart: change BrowseCentral label to action-oriented 'Secure APIs with OAuth' - api-auth-quickstart: fix grammar (it's→its, OAuth2.0→OAuth 2.0-based, malformed sentence, or example→For example) - api-keys: fix intro grammar (gives→give, User Level→user-level, simplify second sentence) - api-keys: wrap Java list-tokens example in try-catch to match error-handling pattern - api-keys: add 'What's next' CardGrid with links to related pages
…list tokens example
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx (1)
42-42:⚠️ Potential issue | 🟡 MinorTypo in D2 diagram:
credetials→credentials.✏️ Suggested fix
-User -> API Client: 4. Saves the API credetials +User -> API Client: 4. Saves the API credentials🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx` at line 42, Typo in the D2 sequence diagram step: change the text "User -> API Client: 4. Saves the API credetials" to "User -> API Client: 4. Saves the API credentials" — locate the D2 diagram string in the document (the line starting with "User -> API Client: 4. Saves the API credetials") and correct the misspelled word "credetials" to "credentials".
♻️ Duplicate comments (1)
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx (1)
415-419:⚠️ Potential issue | 🟠 MajorRealistic-looking
plain_secretvalue triggers Gitleaks scanner.The sample response in step 5 (Register API client's scopes) still carries the full-length synthetic secret, unlike the truncated values elsewhere on this page. Replace it with an obvious placeholder.
🔐 Suggested fix
- "plain_secret": "test_ly8G57h0ErRJSObJI6dShkoaq6bigo11Dxcfa6reKG1kKNVbqBKW4H5Ctmb5UZ0X" + "plain_secret": "<YOUR_PLAIN_SECRET>"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx` around lines 415 - 419, The sample response in the API quickstart still contains a full-length synthetic secret; update the sample under step 5 ("Register API client's scopes") to replace the "plain_secret" value with an obvious placeholder (e.g., "plain_secret": "<REDACTED_SECRET>" or "REDACTED") so it no longer looks like a real secret; locate the JSON block that defines "plain_secret" and swap the value to the placeholder.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx`:
- Around line 367-511: Step 5 (the "Register API client's scopes" Tabs block
with TabItem values "curl", "node", "python") duplicates Step 2's examples;
remove duplication by either collapsing Step 5 into Step 2 as a subsection
titled "Add scopes to your API client" (move the Node.js TabItem into that
subsection and remove the repeated cURL/Python blocks), or keep only the Node.js
TabItem in Step 5 and replace the cURL/Python TabItems with a short
cross-reference to Step 2; update any surrounding headings and the Tabs syncKey
"tech-stack" to reflect the consolidation so examples aren’t duplicated across
create client flows.
- Line 2: The frontmatter title string currently reads "Add OAuth2.0 to your
APIs" and needs a space between "OAuth" and "2.0"; update the title value (the
frontmatter key "title") to "Add OAuth 2.0 to your APIs" so the displayed
heading uses the correct spacing/formatting.
- Around line 519-521: The Aside currently links back to the same page (the text
"See the [quickstart guide](/authenticate/m2m/api-auth-quickstart) for
examples"), causing a self-referential reload; update the link target in the
Aside to point to a specific section anchor on this page (e.g.,
"/authenticate/m2m/api-auth-quickstart#step-2" or the actual heading slug for
step 2) or replace it with a genuinely different page such as the API keys guide
(e.g., "/authenticate/keys/api-keys") so the link provides new, relevant
content; edit the Aside component text where the link is defined to use the
chosen anchor or new path.
In `@src/content/docs/authenticate/m2m/api-keys.mdx`:
- Around line 4-6: The sidebar label in the frontmatter uses title case ("Add
API Keys") and should be changed to sentence case; update the value of the
sidebar.label field in this document (the frontmatter `sidebar: label`) to "Add
API keys" so "keys" is lowercase, preserving the string and keeping the label
concise (1–3 words).
- Around line 40-45: The D2 diagram in the M2M API keys doc contains a typo
"credetials"; update the diagram text to "credentials" wherever "credetials"
appears (e.g., in the D2 block or sequence comment inside the content of
src/content/docs/authenticate/m2m/api-keys.mdx) so the diagram reads
"credentials" correctly; ensure no other spelling variants remain.
---
Outside diff comments:
In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx`:
- Line 42: Typo in the D2 sequence diagram step: change the text "User -> API
Client: 4. Saves the API credetials" to "User -> API Client: 4. Saves the API
credentials" — locate the D2 diagram string in the document (the line starting
with "User -> API Client: 4. Saves the API credetials") and correct the
misspelled word "credetials" to "credentials".
---
Duplicate comments:
In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx`:
- Around line 415-419: The sample response in the API quickstart still contains
a full-length synthetic secret; update the sample under step 5 ("Register API
client's scopes") to replace the "plain_secret" value with an obvious
placeholder (e.g., "plain_secret": "<REDACTED_SECRET>" or "REDACTED") so it no
longer looks like a real secret; locate the JSON block that defines
"plain_secret" and swap the value to the placeholder.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (3)
src/configs/redirects.config.tssrc/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (8)
**/*.mdx
📄 CodeRabbit inference engine (.cursorrules)
**/*.mdx: Use clear, descriptive titles that explain the purpose of the document
Include comprehensive descriptions in frontmatter metadata
Organize content with logical heading hierarchy (H2, H3, H4)
Use tableOfContents property in frontmatter when content has multiple sections
Set appropriate sidebar labels for navigation in frontmatter
Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Use second person perspective ('your application', 'you receive', 'you must') in documentation
Keep sentences concise, aiming for under 25 words per sentence
Explain the 'why' in documentation with phrases like 'This prevents CSRF attacks by...' or 'Use this to validate that...'
Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Use future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Write 1-3 opening paragraphs that explain what users will accomplish, provide context about when/why, preview key concepts, and use direct instructional language
Begin introduction sections with a clear statement of what the guide covers and explain the problem being solved
Use collapsible sections in introduction for sequence diagrams, video demonstrations, data models, and JSON examples with appropriate icons
Use numbered format within Steps component:1. ## Titlewith all step content indented with exactly 3 spaces
Use action-oriented headings in step-by-step guides within Steps components
Include code examples in all 4 languages (Node.js, Python, Go, Java) within Steps co...
Files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
⚙️ CodeRabbit configuration file
**/*.mdx: You are reviewing Scalekit developer documentation written in MDX
(Astro + Starlight framework). Apply ALL of the following checks:Frontmatter
titleMUST be ≤ 60 characters and clearly state what the page does.descriptionMUST be ≤ 160 characters, action-oriented, unique per page.sidebar.labelMUST be present and ≤ 30 characters.sidebar.orderMUST be set on every page that lives inside a section
with siblings, to enforce the journey order in sidebar.config.ts.- Flag any missing
prev/nextlinks on pages that are clearly
part of a sequential flow (e.g., quickstart → implement-login →
complete-login → manage-session → logout).Voice & Style (CLAUDE.md standards)
- Voice: confident, direct, collaborative, instructional.
- Person: second person only ("you", "your application"). Reject "we",
"our", "the developer", "the user".- Tense: present tense for descriptions; imperative mood for instructions.
- Flag weasel words: "simply", "just", "easy", "straightforward",
"obviously", "of course", "note that".- Flag passive voice constructions where active voice is clearer.
- Headings must be sentence case, not Title Case (except proper nouns).
- No heading should end with a colon or period.
Content structure
- How-to guides MUST contain numbered
<Steps>(Starlight component).- Concept pages MUST NOT contain numbered steps — concepts explain, not instruct.
- API reference pages MUST list parameters in a table with Name / Type /
Required / Description columns.- Every page MUST end with a clear "what's next" signal — either a
next:frontmatter link, a<LinkCard>, or an explicit paragraph
pointing the reader forward in the sidebar journey.Code examples
- ALL code examples that show SDK usage MUST include all four language
tabs: Node.js, Python, Go, Java — using<Tabs syncKey="tech-stack">.- SDK variable names are STRICTLY:
scalekit(Node.js),
scalekit_client(Python),scalekitClient(Go), ...
Files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
**/*.{yml,yaml,md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/browsecentral-labels.mdc)
**/*.{yml,yaml,md,mdx}: BrowseCentral labels should be maximum 3-5 words - keep concise but add context when needed
BrowseCentral labels should be action-oriented - start with verbs when possible
BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
BrowseCentral labels should include specific context when needed (e.g., 'Configure Scalekit MCP server', 'Validate incoming API requests')
BrowseCentral labels should use integration context when applicable (e.g., 'Build MCP auth with your existing auth system')
BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'
Files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/deno-docs-style.mdc)
**/*.{md,mdx}: Use sentence case for all titles and headings in MD/MDX documentation
Keep page titles short and descriptive (3–7 words when possible) in MD/MDX documentation
Use outcome-focused headings that describe results, not categories (e.g., 'Run a script' not 'Scripts')
Avoid gerunds in headings when an imperative works - prefer 'Configure proxies' over 'Configuring proxies'
Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Use sentence case in sidebar labels without punctuation
Set frontmatter title in sentence case with a clear outcome; description in one sentence (≤160 chars); sidebar.label as shorter form of title; enable tableOfContents on longer pages
Start documentation pages with a one-paragraph overview explaining what the page covers and when to use it
Present the primary use case (80% path) first in documentation, with edge cases later
Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Break up long documentation sections with subheadings every 3–6 paragraphs
Use asides for important notes, tips, cautions, and references in documentation
Provide runnable, minimal code examples that work as-is in documentation
Prefer CLI-first examples and show file layout when helpful in documentation
Label code blocks with titles for context (e.g., 'Terminal', 'main.ts') in documentation
Keep code block annotations brief and purposeful - annotate only what matters
Use consistent variable and file names across a documentation page
Use descriptive link text in documentation (e.g., 'See permission flags' not 'click here')
Prefer relative links for internal documentation pages and include anchors for section references
Reference APIs consistently using backticks for code, file names, CLI flags, and endpoints
Use backticks for code, file names, CLI flags, and endpoints in documentation
Use lists for options and features in documentation; tables only when comparisons are cleare...
Files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
src/content/docs/authenticate/**/*.mdx
⚙️ CodeRabbit configuration file
src/content/docs/authenticate/**/*.mdx: This page lives in the primary authentication section.
- If it's a quickstart or step-based guide, it MUST use
<Steps>.- Auth method pages (passwordless, social, SSO, passkeys) MUST include
a brief "when to use this" section before the implementation steps.- Any reference to tokens (idToken, accessToken, refreshToken) MUST
clarify: what it contains, its lifetime, and how to use it securely.- The FSA quickstart (
authenticate/fsa/quickstart.mdx) is the
canonical entry point — no other page should duplicate its 5-step
install→redirect→callback→session→logout structure.
Files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
**/*.{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:
src/configs/redirects.config.ts
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}: Good comments do not excuse unclear code - refactor the code to be self-explanatory instead of using comments to explain poorly written code; use better variable names, function names, and code structure
Comments should dispel confusion, not cause it - ensure comments clarify rather than obscure the code's purpose; avoid cryptic or joke comments
Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Provide links to the original source of copied code - always attribute code copied from external sources with URLs to Stack Overflow answers, GitHub repositories, or documentation
Include links to external references where helpful - reference standards, RFCs, and official documentation; link to relevant specifications when implementing protocols
Add comments when fixing bugs - document bug fixes with context about the issue, reference issue trackers and bug reports, and explain workarounds and their limitations
Use comments to mark incomplete implementations - use standard formats for TODO, FIXME, and NOTE comments with context about what needs to be done and reference issue trackers when possible
Always document public APIs with function/class comments - explain the purpose, parameters, return values, and exceptions; include usage examples for complex functions
Include file headers with copyright information, license, and authorship - provide a brief description of the file's purpose and document dependencies and requirements
Files:
src/configs/redirects.config.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Use JSDoc standards for all function, class, and complex logic comments in JavaScript/TypeScript - include parameter descriptions (
@param), return values (@returns), types (@type), and descriptions; document exceptions and edge cases
Files:
src/configs/redirects.config.ts
**/*.{ts,js,mjs}
⚙️ CodeRabbit configuration file
**/*.{ts,js,mjs}: Do NOT enforce code-commenting style rules on these files.
Specifically, do not flag:
- Comments that "duplicate" or restate what the code does.
- Missing comments on bug fixes, workarounds, or issue references.
- Missing inline documentation or explanatory comments.
Code comments are at the author's discretion.
Files:
src/configs/redirects.config.ts
🧠 Learnings (35)
📓 Common learnings
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
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">`.
📚 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 present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 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:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/configs/redirects.config.tssrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-10T05:32:59.967Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should be action-oriented - start with verbs when possible
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 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 future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-18T02:55:23.285Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-18T02:55:23.285Z
Learning: Applies to **/*.{md,mdx} : Use SDK variable names: Node.js `scalekit`, Python `scalekit_client`, Go `scalekitClient`, Java `scalekitClient`
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/configs/redirects.config.tssrc/content/docs/authenticate/m2m/api-keys.mdx
📚 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:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 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 direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 : Include configuration comments in code examples: '// Get the signing secret from Scalekit dashboard > Interceptors tab'
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-18T02:55:23.285Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-18T02:55:23.285Z
Learning: Applies to **/*.{md,mdx} : Include security comments in code examples explaining threats and security implications
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.mdx : Use Tabs/TabItem components for multi-language or multi-framework examples in MDX documentation
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 : Tabs components within Steps must be indented with 3 spaces, TabItem at same level as parent Tabs, code blocks properly indented within TabItem
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-30T18:18:50.883Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx:31-49
Timestamp: 2026-01-30T18:18:50.883Z
Learning: In all Scalekit documentation files (MDX), treat the terms 'Applications', 'Single Page Application (SPA)', 'Native Application', and 'Web Application' as proper nouns and preserve their capitalization in headings and body text. Ensure these terms remain capitalized even when used in sentence case or within prose.
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-04T12:47:16.544Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 412
File: src/content/docs/dev-kit/tools/scalekit-dryrun.mdx:1-23
Timestamp: 2026-02-04T12:47:16.544Z
Learning: In scalekit-inc/developer-docs, the MDX frontmatter field order is required only when the sidebar configuration points to a directory (for auto-generation). If the sidebar.config.ts references a specific file path, the order field is not required. Apply this check to all MDX files under src/content/docs: if a file contributes to an auto-generated sidebar (directory path), ensure order is present; if it’s linked to a concrete file, order can be omitted. Use sidebar.config.ts to determine whether a given MDX file falls under directory-based vs file-specific sidebar references.
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-25T08:57:12.201Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/quickstart.mdx:2-10
Timestamp: 2026-02-25T08:57:12.201Z
Learning: In Scalekit developer-docs (Astro Starlight), do not auto-suggest adding tableOfContents in frontmatter unless the user explicitly overrides the default behavior. The default enables tableOfContents with minHeadingLevel 2 and maxHeadingLevel 3. Only set tableOfContents when you want to customize heading levels or disable it entirely; otherwise omit it for other docs.
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-25T03:34:41.147Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:31-31
Timestamp: 2026-02-25T03:34:41.147Z
Learning: In MDX files, import { Code } from 'astrojs/starlight/components' only if the MDX content actually uses the <Code> component. If the file uses only fenced code blocks (```), the import is not required. Apply this guideline to all MDX files (e.g., src/content/docs/**/*.mdx) to avoid unnecessary imports and reduce bundle size.
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-30T18:20:07.851Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:1-6
Timestamp: 2026-01-30T18:20:07.851Z
Learning: In the scalekit-inc/developer-docs repository, MDX files under `src/content/docs/authenticate/fsa/multiapp/` do not use `order` or `tags` fields in their frontmatter. Ordering and grouping are managed centrally in `src/configs/sidebar.config.ts`.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 : Always include security comments in security-related code with pattern: '// Security: ALWAYS verify requests are from Scalekit before processing'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 : Include context comments explaining what's happening in code: '// Extract encrypted tokens from request cookies', '// Decrypt the access token before validation'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-18T18:25:59.260Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 438
File: CONTRIBUTING.md:1-7
Timestamp: 2026-02-18T18:25:59.260Z
Learning: In scalekit-inc/developer-docs, root-level markdown files like CONTRIBUTING.md and README.md are standard GitHub repository files and do not require frontmatter. Only MDX files under src/content/docs/ that are processed by the Starlight docs system need frontmatter with title, description, and navigation metadata.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 : Always include error handling in code examples showing both success and error paths
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 : Include todo/next step comments in code examples: '// TODO: Store user session (next guide covers this)', '// Next step: Create a session and log in the user'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Start documentation pages with a one-paragraph overview explaining what the page covers and when to use it
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Don't skip important context or prerequisites in documentation
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
🪛 Gitleaks (8.30.0)
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
[high] 417-417: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🔇 Additional comments (2)
src/configs/redirects.config.ts (1)
276-277: LGTM — two-hop redirect correctly collapsed.Both
/m2m/scopesand/guides/m2m/scopes/now point directly to/authenticate/m2m/api-auth-quickstart/with no intermediate hop.src/content/docs/authenticate/m2m/api-keys.mdx (1)
901-948:⚠️ Potential issue | 🔴 CriticalJava example uses incorrect API — code will not compile with the actual Scalekit Java SDK.
The code calls
scalekitClient.tokens().validate(token)returningValidateTokenResponse, but the official Java SDK (v2.0.11) does not have this API. The actual method isscalekitClient.authentication().validateAccessTokenAndGetClaims(token), which returnsMap<String, Object>, not aValidateTokenResponseobject withgetTokenInfo().This makes the entire example fundamentally broken: the imports, method call, return type handling, and type cast are all incorrect for the actual SDK.
🐛 Correct Java implementation
import com.scalekit.exceptions.TokenInvalidException; import com.scalekit.ScalekitClient; import java.util.Map; `@Component` public class TokenAuthFilter extends OncePerRequestFilter { private final ScalekitClient scalekitClient; public TokenAuthFilter(ScalekitClient scalekitClient) { this.scalekitClient = scalekitClient; } `@Override` protected void doFilterInternal( HttpServletRequest request, HttpServletResponse response, FilterChain filterChain ) throws ServletException, IOException { String authHeader = request.getHeader("Authorization"); if (authHeader == null || !authHeader.startsWith("Bearer ")) { // Reject requests without credentials to prevent unauthorized access response.sendError(401, "Missing authorization token"); return; } String token = authHeader.substring(7); try { // Server-side validation — Scalekit checks token status in real time Map<String, Object> tokenClaims = scalekitClient.authentication() .validateAccessTokenAndGetClaims(token); // Attach token context for downstream handlers request.setAttribute("tokenInfo", tokenClaims); filterChain.doFilter(request, response); } catch (TokenInvalidException e) { // Revoked, expired, or malformed tokens are rejected immediately response.sendError(401, "Invalid or expired token"); } } } // Access in your controller `@GetMapping`("/api/resources") public ResponseEntity<?> getResources(HttpServletRequest request) { Map<String, Object> tokenInfo = (Map<String, Object>) request.getAttribute("tokenInfo"); String orgId = (String) tokenInfo.get("organization_id"); // Serve resources scoped to this organization }⛔ Skipped due to learnings
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">`.Learnt from: saif-at-scalekit Repo: scalekit-inc/developer-docs PR: 424 File: public/api/scalekit.scalar.json:3451-3457 Timestamp: 2026-02-10T05:32:59.967Z Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.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 present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
…tle, fix self-referential link in Aside
saif-at-scalekit
left a comment
saif-at-scalekit
left a comment
There was a problem hiding this comment.
Thanks for addressing all coderabbit pr comments, and adding this guide.
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx (1)
74-232:⚠️ Potential issue | 🟠 MajorAdd Go and Java tabs to SDK sections for full language parity.
These sections include SDK usage but do not consistently provide all four required language tabs (
Node.js,Python,Go,Java) with<Tabs syncKey="tech-stack">.As per coding guidelines, "
ALL code examples that show SDK usage MUST include all four language tabs: Node.js, Python, Go, Java — using <Tabs syncKey='tech-stack'>."Also applies to: 244-270, 373-511, 552-672
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx` around lines 74 - 232, The Tabs block using Tabs syncKey="tech-stack" currently only contains TabItem entries for "curl" and "python" (see TabItem value="curl" and TabItem value="python"); add matching TabItem entries for Go and Java with equivalent SDK examples and sample responses so all four languages (Node.js, Python, Go, Java) are present; repeat the same fix for the other Tabs blocks referenced in the comment (sections around the later ranges) to ensure full language parity and consistent syncKey usage.
♻️ Duplicate comments (3)
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx (3)
146-147:⚠️ Potential issue | 🟡 MinorUse fully redacted placeholders for
plain_secretsample values.
test_...-shaped values still look credential-like and can trigger secret scanners. Use an unmistakable placeholder such as<REDACTED_SECRET>.🔐 Proposed fix
- "plain_secret": "test_ly8G57h0ErRJSObJI6dShkoa..." + "plain_secret": "<REDACTED_SECRET>" ... - "plain_secret": "test_ly8G57h0ErRJSObJI6dShkoaq6bigo11Dxcf.." + "plain_secret": "<REDACTED_SECRET>"As per coding guidelines, "
Security-sensitive operations (tokens, cookies, secrets) MUST include inline comments explaining the security implication or threat mitigated."Also applies to: 226-227
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx` around lines 146 - 147, Replace the sample credential value for the JSON key "plain_secret" with a fully redacted placeholder (e.g. "<REDACTED_SECRET>") everywhere it appears in this document (including the other occurrence noted) and add a short inline comment next to the example explaining the security implication (e.g., that example secrets must be redacted to avoid secret-scanner alerts and accidental disclosure); update the example blocks that contain "plain_secret" so they no longer look like real tokens and include the inline comment adjacent to the redacted placeholder.
42-42:⚠️ Potential issue | 🟡 MinorFix typo in sequence diagram text (
credetials→credentials).Line 42 has a visible typo in user-facing content.
✏️ Proposed fix
-User -> API Client: 4. Saves the API credetials +User -> API Client: 4. Saves the API credentialsAs per coding guidelines, "
Write simply and directly with short sentences and plain language in documentation."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx` at line 42, Update the sequence diagram text that currently reads "User -> API Client: 4. Saves the API credetials" to correct the typo by replacing "credetials" with "credentials" so the line becomes "User -> API Client: 4. Saves the API credentials"; locate and edit the sequence diagram string in the document (the line containing that exact phrase) to make this one-word correction.
672-672:⚠️ Potential issue | 🟡 MinorAdd a clear “what’s next” pointer at the end of the page.
The page ends without a final navigation signal (
next:frontmatter link,<LinkCard>, or explicit forward-link paragraph).As per coding guidelines, "
Every page MUST end with a clear 'what's next' signal."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx` at line 672, The page lacks a final "what's next" navigation cue; add one by either adding a next: frontmatter entry (next: "<slug-or-title>") or appending a visual forward-link using the <LinkCard> component or a short forward-link paragraph at the end of api-auth-quickstart.mdx that points readers to the next logical doc (e.g., deeper auth topics or examples); ensure the link text and target are meaningful and follow existing site conventions.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx`:
- Line 78: Replace the hardcoded external URL
"http://docs.scalekit.com/apis#description/authentication" in the markdown line
with a root-relative internal link, e.g.
"/docs/apis#description/authentication", so the line reads: "For authentication
details, see: /docs/apis#description/authentication"; update the text in
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx accordingly.
In `@src/content/docs/authenticate/m2m/api-keys.mdx`:
- Around line 345-355: The code checks only for errors.Is(err,
scalekit.ErrTokenValidationFailed) but still proceeds to read result.TokenInfo
when err may be non-nil for other reasons; update the ValidateToken handling
(the call to scalekitClient.Token().ValidateToken in these snippets) to first
check if err != nil and handle/log/return for any non-nil error (using errors.Is
for specific ErrTokenValidationFailed for a custom message), and only after
err==nil access result and result.TokenInfo (also guard result and
result.TokenInfo for nil before reading OrganizationId/GetUserId/CustomClaims);
apply the same fix pattern to the other two Go snippets that call ValidateToken.
- Around line 968-981: The document ending at the "What's next" CardGrid
currently lacks the required STYLE-CHECK footer; open the file containing the
final CardGrid/LinkCard block (the snippet showing "What's next" using CardGrid
and LinkCard) and append a single-line footer exactly in the form "STYLE-CHECK:
[PASSED | TODO]" (choose PASSED or TODO as appropriate) on its own line at the
end of the file so the doc complies with the STYLE-CHECK guideline.
- Around line 51-116: The document currently presents the main how-to flow as
plain headings and sections; wrap the core sequence (Install the SDK → Create a
token → Validate → List → Invalidate → Protect endpoints) in the Starlight
<Steps> component so the guide is rendered as an ordered, numbered flow; replace
the standalone "## Install the SDK" and the subsequent related sections with a
single <Steps> block containing ordered <Step> (or StepItem) entries that
include the existing content (keep components like <InstallSDK /> and the <Tabs>
code examples inside the appropriate step), ensuring each step has a clear title
and the same content preserved in the same order.
---
Outside diff comments:
In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx`:
- Around line 74-232: The Tabs block using Tabs syncKey="tech-stack" currently
only contains TabItem entries for "curl" and "python" (see TabItem value="curl"
and TabItem value="python"); add matching TabItem entries for Go and Java with
equivalent SDK examples and sample responses so all four languages (Node.js,
Python, Go, Java) are present; repeat the same fix for the other Tabs blocks
referenced in the comment (sections around the later ranges) to ensure full
language parity and consistent syncKey usage.
---
Duplicate comments:
In `@src/content/docs/authenticate/m2m/api-auth-quickstart.mdx`:
- Around line 146-147: Replace the sample credential value for the JSON key
"plain_secret" with a fully redacted placeholder (e.g. "<REDACTED_SECRET>")
everywhere it appears in this document (including the other occurrence noted)
and add a short inline comment next to the example explaining the security
implication (e.g., that example secrets must be redacted to avoid secret-scanner
alerts and accidental disclosure); update the example blocks that contain
"plain_secret" so they no longer look like real tokens and include the inline
comment adjacent to the redacted placeholder.
- Line 42: Update the sequence diagram text that currently reads "User -> API
Client: 4. Saves the API credetials" to correct the typo by replacing
"credetials" with "credentials" so the line becomes "User -> API Client: 4.
Saves the API credentials"; locate and edit the sequence diagram string in the
document (the line containing that exact phrase) to make this one-word
correction.
- Line 672: The page lacks a final "what's next" navigation cue; add one by
either adding a next: frontmatter entry (next: "<slug-or-title>") or appending a
visual forward-link using the <LinkCard> component or a short forward-link
paragraph at the end of api-auth-quickstart.mdx that points readers to the next
logical doc (e.g., deeper auth topics or examples); ensure the link text and
target are meaningful and follow existing site conventions.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
src/content/docs/authenticate/m2m/api-auth-quickstart.mdxsrc/content/docs/authenticate/m2m/api-keys.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (4)
**/*.mdx
📄 CodeRabbit inference engine (.cursorrules)
**/*.mdx: Use clear, descriptive titles that explain the purpose of the document
Include comprehensive descriptions in frontmatter metadata
Organize content with logical heading hierarchy (H2, H3, H4)
Use tableOfContents property in frontmatter when content has multiple sections
Set appropriate sidebar labels for navigation in frontmatter
Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Use second person perspective ('your application', 'you receive', 'you must') in documentation
Keep sentences concise, aiming for under 25 words per sentence
Explain the 'why' in documentation with phrases like 'This prevents CSRF attacks by...' or 'Use this to validate that...'
Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Use future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Write 1-3 opening paragraphs that explain what users will accomplish, provide context about when/why, preview key concepts, and use direct instructional language
Begin introduction sections with a clear statement of what the guide covers and explain the problem being solved
Use collapsible sections in introduction for sequence diagrams, video demonstrations, data models, and JSON examples with appropriate icons
Use numbered format within Steps component:1. ## Titlewith all step content indented with exactly 3 spaces
Use action-oriented headings in step-by-step guides within Steps components
Include code examples in all 4 languages (Node.js, Python, Go, Java) within Steps co...
Files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
⚙️ CodeRabbit configuration file
**/*.mdx: You are reviewing Scalekit developer documentation written in MDX
(Astro + Starlight framework). Apply ALL of the following checks:Frontmatter
titleMUST be ≤ 60 characters and clearly state what the page does.descriptionMUST be ≤ 160 characters, action-oriented, unique per page.sidebar.labelMUST be present and ≤ 30 characters.sidebar.orderMUST be set on every page that lives inside a section
with siblings, to enforce the journey order in sidebar.config.ts.- Flag any missing
prev/nextlinks on pages that are clearly
part of a sequential flow (e.g., quickstart → implement-login →
complete-login → manage-session → logout).Voice & Style (CLAUDE.md standards)
- Voice: confident, direct, collaborative, instructional.
- Person: second person only ("you", "your application"). Reject "we",
"our", "the developer", "the user".- Tense: present tense for descriptions; imperative mood for instructions.
- Flag weasel words: "simply", "just", "easy", "straightforward",
"obviously", "of course", "note that".- Flag passive voice constructions where active voice is clearer.
- Headings must be sentence case, not Title Case (except proper nouns).
- No heading should end with a colon or period.
Content structure
- How-to guides MUST contain numbered
<Steps>(Starlight component).- Concept pages MUST NOT contain numbered steps — concepts explain, not instruct.
- API reference pages MUST list parameters in a table with Name / Type /
Required / Description columns.- Every page MUST end with a clear "what's next" signal — either a
next:frontmatter link, a<LinkCard>, or an explicit paragraph
pointing the reader forward in the sidebar journey.Code examples
- ALL code examples that show SDK usage MUST include all four language
tabs: Node.js, Python, Go, Java — using<Tabs syncKey="tech-stack">.- SDK variable names are STRICTLY:
scalekit(Node.js),
scalekit_client(Python),scalekitClient(Go), ...
Files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
**/*.{yml,yaml,md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/browsecentral-labels.mdc)
**/*.{yml,yaml,md,mdx}: BrowseCentral labels should be maximum 3-5 words - keep concise but add context when needed
BrowseCentral labels should be action-oriented - start with verbs when possible
BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
BrowseCentral labels should include specific context when needed (e.g., 'Configure Scalekit MCP server', 'Validate incoming API requests')
BrowseCentral labels should use integration context when applicable (e.g., 'Build MCP auth with your existing auth system')
BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'
Files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/deno-docs-style.mdc)
**/*.{md,mdx}: Use sentence case for all titles and headings in MD/MDX documentation
Keep page titles short and descriptive (3–7 words when possible) in MD/MDX documentation
Use outcome-focused headings that describe results, not categories (e.g., 'Run a script' not 'Scripts')
Avoid gerunds in headings when an imperative works - prefer 'Configure proxies' over 'Configuring proxies'
Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Use sentence case in sidebar labels without punctuation
Set frontmatter title in sentence case with a clear outcome; description in one sentence (≤160 chars); sidebar.label as shorter form of title; enable tableOfContents on longer pages
Start documentation pages with a one-paragraph overview explaining what the page covers and when to use it
Present the primary use case (80% path) first in documentation, with edge cases later
Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Break up long documentation sections with subheadings every 3–6 paragraphs
Use asides for important notes, tips, cautions, and references in documentation
Provide runnable, minimal code examples that work as-is in documentation
Prefer CLI-first examples and show file layout when helpful in documentation
Label code blocks with titles for context (e.g., 'Terminal', 'main.ts') in documentation
Keep code block annotations brief and purposeful - annotate only what matters
Use consistent variable and file names across a documentation page
Use descriptive link text in documentation (e.g., 'See permission flags' not 'click here')
Prefer relative links for internal documentation pages and include anchors for section references
Reference APIs consistently using backticks for code, file names, CLI flags, and endpoints
Use backticks for code, file names, CLI flags, and endpoints in documentation
Use lists for options and features in documentation; tables only when comparisons are cleare...
Files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
src/content/docs/authenticate/**/*.mdx
⚙️ CodeRabbit configuration file
src/content/docs/authenticate/**/*.mdx: This page lives in the primary authentication section.
- If it's a quickstart or step-based guide, it MUST use
<Steps>.- Auth method pages (passwordless, social, SSO, passkeys) MUST include
a brief "when to use this" section before the implementation steps.- Any reference to tokens (idToken, accessToken, refreshToken) MUST
clarify: what it contains, its lifetime, and how to use it securely.- The FSA quickstart (
authenticate/fsa/quickstart.mdx) is the
canonical entry point — no other page should duplicate its 5-step
install→redirect→callback→session→logout structure.
Files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
🧠 Learnings (41)
📓 Common learnings
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
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">`.
📚 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:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 : Include configuration comments in code examples: '// Get the signing secret from Scalekit dashboard > Interceptors tab'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-02-10T05:32:59.967Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-30T18:20:07.851Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:1-6
Timestamp: 2026-01-30T18:20:07.851Z
Learning: In the scalekit-inc/developer-docs repository, MDX files under `src/content/docs/authenticate/fsa/multiapp/` do not use `order` or `tags` fields in their frontmatter. Ordering and grouping are managed centrally in `src/configs/sidebar.config.ts`.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-02-18T02:55:23.285Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-18T02:55:23.285Z
Learning: Applies to **/*.{md,mdx} : Use SDK variable names: Node.js `scalekit`, Python `scalekit_client`, Go `scalekitClient`, Java `scalekitClient`
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 : Always include security comments in security-related code with pattern: '// Security: ALWAYS verify requests are from Scalekit before processing'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 : Include context comments explaining what's happening in code: '// Extract encrypted tokens from request cookies', '// Decrypt the access token before validation'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-02-18T18:25:59.260Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 438
File: CONTRIBUTING.md:1-7
Timestamp: 2026-02-18T18:25:59.260Z
Learning: In scalekit-inc/developer-docs, root-level markdown files like CONTRIBUTING.md and README.md are standard GitHub repository files and do not require frontmatter. Only MDX files under src/content/docs/ that are processed by the Starlight docs system need frontmatter with title, description, and navigation metadata.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 : Always include error handling in code examples showing both success and error paths
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 : Include todo/next step comments in code examples: '// TODO: Store user session (next guide covers this)', '// Next step: Create a session and log in the user'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Use sentence case in sidebar labels without punctuation
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Use sentence case for headings near code examples (e.g., 'Authenticate users')
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should be action-oriented - start with verbs when possible
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Set frontmatter title in sentence case with a clear outcome; description in one sentence (≤160 chars); sidebar.label as shorter form of title; enable tableOfContents on longer pages
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Set concise sidebar labels that match user vocabulary in navigation metadata
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-30T18:18:50.883Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx:31-49
Timestamp: 2026-01-30T18:18:50.883Z
Learning: In all Scalekit documentation files (MDX), treat the terms 'Applications', 'Single Page Application (SPA)', 'Native Application', and 'Web Application' as proper nouns and preserve their capitalization in headings and body text. Ensure these terms remain capitalized even when used in sentence case or within prose.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-02-04T12:47:16.544Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 412
File: src/content/docs/dev-kit/tools/scalekit-dryrun.mdx:1-23
Timestamp: 2026-02-04T12:47:16.544Z
Learning: In scalekit-inc/developer-docs, the MDX frontmatter field order is required only when the sidebar configuration points to a directory (for auto-generation). If the sidebar.config.ts references a specific file path, the order field is not required. Apply this check to all MDX files under src/content/docs: if a file contributes to an auto-generated sidebar (directory path), ensure order is present; if it’s linked to a concrete file, order can be omitted. Use sidebar.config.ts to determine whether a given MDX file falls under directory-based vs file-specific sidebar references.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-02-25T08:57:12.201Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/quickstart.mdx:2-10
Timestamp: 2026-02-25T08:57:12.201Z
Learning: In Scalekit developer-docs (Astro Starlight), do not auto-suggest adding tableOfContents in frontmatter unless the user explicitly overrides the default behavior. The default enables tableOfContents with minHeadingLevel 2 and maxHeadingLevel 3. Only set tableOfContents when you want to customize heading levels or disable it entirely; otherwise omit it for other docs.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-02-25T03:34:41.147Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:31-31
Timestamp: 2026-02-25T03:34:41.147Z
Learning: In MDX files, import { Code } from 'astrojs/starlight/components' only if the MDX content actually uses the <Code> component. If the file uses only fenced code blocks (```), the import is not required. Apply this guideline to all MDX files (e.g., src/content/docs/**/*.mdx) to avoid unnecessary imports and reduce bundle size.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdxsrc/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-02-18T02:55:23.285Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-18T02:55:23.285Z
Learning: Applies to **/*.{md,mdx} : Include security comments in code examples explaining threats and security implications
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Use descriptive link text in documentation (e.g., 'See permission flags' not 'click here')
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Use descriptive link text and avoid 'click here' in documentation
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:47:33.407Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/comment-standards.mdc:0-0
Timestamp: 2026-01-13T12:47:33.407Z
Learning: Applies to **/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy} : Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.mdx : Use Tabs/TabItem components for multi-language or multi-framework examples in MDX documentation
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
📚 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 : Tabs components within Steps must be indented with 3 spaces, TabItem at same level as parent Tabs, code blocks properly indented within TabItem
Applied to files:
src/content/docs/authenticate/m2m/api-auth-quickstart.mdx
🔇 Additional comments (1)
src/content/docs/authenticate/m2m/api-keys.mdx (1)
60-109:⚠️ Potential issue | 🟡 MinorUse file-path code block titles consistently.
Multiple blocks use framework labels (
Express.js,Flask,Gin,Spring Boot) or omittitleentirely. Replace with concrete file-path titles (for example,title="middleware/auth.ts"ortitle="app.py").As per coding guidelines, "
Code blocks MUST have a title= attribute showing the file path."Also applies to: 124-194
⛔ Skipped due to learnings
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 'title' attribute in code blocks to show framework names: 'Express.js', 'Flask', 'Gin', 'Spring Boot'Learnt from: CR Repo: scalekit-inc/developer-docs PR: 0 File: .cursor/rules/deno-docs-style.mdc:0-0 Timestamp: 2026-01-13T12:47:52.148Z Learning: Applies to **/*.{md,mdx} : Label code blocks with titles for context (e.g., 'Terminal', 'main.ts') in documentationLearnt from: CR Repo: scalekit-inc/developer-docs PR: 0 File: .cursor/rules/expressive-code.mdc:0-0 Timestamp: 2026-01-13T12:48:19.565Z Learning: Applies to **/*.{md,mdx} : Use Expressive Code consistently across all documentation pages, preferring Starlight's `<Code>` component for rich features (titles, markers, accurate syntax highlighting) and dynamic snippets over fenced code blocksLearnt from: CR Repo: scalekit-inc/developer-docs PR: 0 File: .cursor/rules/deno-docs-style.mdc:0-0 Timestamp: 2026-01-13T12:47:52.148Z Learning: Applies to **/*.{md,mdx} : Reference APIs consistently using backticks for code, file names, CLI flags, and endpointsLearnt from: CR Repo: scalekit-inc/developer-docs PR: 0 File: .cursor/rules/expressive-code.mdc:0-0 Timestamp: 2026-01-13T12:48:19.565Z Learning: Applies to **/*.mdx : Provide a `title` prop to the `<Code>` component when the snippet represents a fileLearnt from: CR Repo: scalekit-inc/developer-docs PR: 0 File: .cursor/rules/documentation-guide.mdc:0-0 Timestamp: 2026-01-13T12:48:11.566Z Learning: Applies to **/*.{md,mdx} : Use clear, descriptive page titles that state the purpose and outcome in documentationLearnt 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 Tab labels for multi-language examples: 'Node.js', 'Python', 'Go', 'Java' with TabItem values 'node', 'python'/'py', 'go'/'golang', 'java'Learnt from: CR Repo: scalekit-inc/developer-docs PR: 0 File: .cursor/rules/deno-docs-style.mdc:0-0 Timestamp: 2026-01-13T12:47:52.148Z Learning: Applies to **/*.{md,mdx} : Use backticks for code, file names, CLI flags, and endpoints in documentationLearnt from: CR Repo: scalekit-inc/developer-docs PR: 0 File: .cursor/rules/documentation-guide.mdc:0-0 Timestamp: 2026-01-13T12:48:11.566Z Learning: Applies to **/*.{md,mdx} : Write descriptive titles and meta descriptions that reflect user tasks for SEOLearnt from: CR Repo: scalekit-inc/developer-docs PR: 0 File: .cursor/rules/deno-docs-style.mdc:0-0 Timestamp: 2026-01-13T12:47:52.148Z Learning: Applies to **/*.{md,mdx} : Keep code block annotations brief and purposeful - annotate only what mattersLearnt from: CR Repo: scalekit-inc/developer-docs PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-02-18T02:55:23.285Z Learning: Applies to **/*.{md,mdx} : Use SDK variable names: Node.js `scalekit`, Python `scalekit_client`, Go `scalekitClient`, Java `scalekitClient`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'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">`.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Around line 15-20: Fix the heading/content mismatch by moving the
documentation-first policy text currently under the "SDK Variable Names
(CRITICAL)" heading into the empty "Documentation-First Development" heading;
change both headings to sentence case ("Documentation-first development" and
"SDK variable names (critical)") and ensure the SDK variable names section
contains only variable-name-specific guidance (and a clear CRITICAL note) not
the documentation-first policy; add the required blank line after the "SDK
variable names (critical)" heading to satisfy MD022 and then verify any code
examples or docs that reference SDK variable guidance reflect the corrected
heading/content placement.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (3)
CLAUDE.mdsrc/configs/sidebar.config.tssrc/content/docs/guides/m2m/api-auth-m2m-clients.mdx
💤 Files with no reviewable changes (1)
- src/content/docs/guides/m2m/api-auth-m2m-clients.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (8)
**/*.{yml,yaml,md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/browsecentral-labels.mdc)
**/*.{yml,yaml,md,mdx}: BrowseCentral labels should be maximum 3-5 words - keep concise but add context when needed
BrowseCentral labels should be action-oriented - start with verbs when possible
BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
BrowseCentral labels should include specific context when needed (e.g., 'Configure Scalekit MCP server', 'Validate incoming API requests')
BrowseCentral labels should use integration context when applicable (e.g., 'Build MCP auth with your existing auth system')
BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'
Files:
CLAUDE.md
**/*.{md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/deno-docs-style.mdc)
**/*.{md,mdx}: Use sentence case for all titles and headings in MD/MDX documentation
Keep page titles short and descriptive (3–7 words when possible) in MD/MDX documentation
Use outcome-focused headings that describe results, not categories (e.g., 'Run a script' not 'Scripts')
Avoid gerunds in headings when an imperative works - prefer 'Configure proxies' over 'Configuring proxies'
Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Use sentence case in sidebar labels without punctuation
Set frontmatter title in sentence case with a clear outcome; description in one sentence (≤160 chars); sidebar.label as shorter form of title; enable tableOfContents on longer pages
Start documentation pages with a one-paragraph overview explaining what the page covers and when to use it
Present the primary use case (80% path) first in documentation, with edge cases later
Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Break up long documentation sections with subheadings every 3–6 paragraphs
Use asides for important notes, tips, cautions, and references in documentation
Provide runnable, minimal code examples that work as-is in documentation
Prefer CLI-first examples and show file layout when helpful in documentation
Label code blocks with titles for context (e.g., 'Terminal', 'main.ts') in documentation
Keep code block annotations brief and purposeful - annotate only what matters
Use consistent variable and file names across a documentation page
Use descriptive link text in documentation (e.g., 'See permission flags' not 'click here')
Prefer relative links for internal documentation pages and include anchors for section references
Reference APIs consistently using backticks for code, file names, CLI flags, and endpoints
Use backticks for code, file names, CLI flags, and endpoints in documentation
Use lists for options and features in documentation; tables only when comparisons are cleare...
Files:
CLAUDE.md
CLAUDE.md
⚙️ CodeRabbit configuration file
CLAUDE.md: CLAUDE.md is the quick-reference for AI assistant behavior in this repo.
- It MUST reference
.specify/memory/constitution.mdas the single
source of truth.- SDK variable names section is CRITICAL — any change here must be
intentional and reflected across all code examples in the docs.- The "Quality Checklist" section must end every AI-generated draft
withSTYLE-CHECK: [PASSED | TODO].
Files:
CLAUDE.md
**/*.{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:
src/configs/sidebar.config.ts
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}: Good comments do not excuse unclear code - refactor the code to be self-explanatory instead of using comments to explain poorly written code; use better variable names, function names, and code structure
Comments should dispel confusion, not cause it - ensure comments clarify rather than obscure the code's purpose; avoid cryptic or joke comments
Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Provide links to the original source of copied code - always attribute code copied from external sources with URLs to Stack Overflow answers, GitHub repositories, or documentation
Include links to external references where helpful - reference standards, RFCs, and official documentation; link to relevant specifications when implementing protocols
Add comments when fixing bugs - document bug fixes with context about the issue, reference issue trackers and bug reports, and explain workarounds and their limitations
Use comments to mark incomplete implementations - use standard formats for TODO, FIXME, and NOTE comments with context about what needs to be done and reference issue trackers when possible
Always document public APIs with function/class comments - explain the purpose, parameters, return values, and exceptions; include usage examples for complex functions
Include file headers with copyright information, license, and authorship - provide a brief description of the file's purpose and document dependencies and requirements
Files:
src/configs/sidebar.config.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Use JSDoc standards for all function, class, and complex logic comments in JavaScript/TypeScript - include parameter descriptions (
@param), return values (@returns), types (@type), and descriptions; document exceptions and edge cases
Files:
src/configs/sidebar.config.ts
src/configs/sidebar.config.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Left Sidebar navigation is configured via
src/configs/sidebar.config.ts; Secondary Navigation is managed throughsrc/components/overrides/Header.astroandsrc/components/SecondaryNav.astro; changes to navigation structure MUST be coordinated across both configurations
Files:
src/configs/sidebar.config.ts
⚙️ CodeRabbit configuration file
src/configs/sidebar.config.ts: This file defines the user journey across ALL documentation sections.
When reviewing changes to this file:
- Verify that reordered items do not break the logical learning sequence
(e.g., "complete-login" must always come after "implement-login").- New items added to the FSA sidebar must follow the journey sequence:
Getting Started → User Auth → Auth Methods → Users & Orgs →
Authorization → Multi-App → APIs → Customize → Go Live.- Commented-out items (TODO) are acceptable but must include a comment
explaining WHY they are hidden.sidebarToSecondaryNavmappings MUST be updated whenever a new
sidebar section (id) is added.- External links MUST include the
attrsblock with
target: '_blank',rel: 'noopener noreferrer',class: 'external-link'.
Files:
src/configs/sidebar.config.ts
**/*.{ts,js,mjs}
⚙️ CodeRabbit configuration file
**/*.{ts,js,mjs}: Do NOT enforce code-commenting style rules on these files.
Specifically, do not flag:
- Comments that "duplicate" or restate what the code does.
- Missing comments on bug fixes, workarounds, or issue references.
- Missing inline documentation or explanatory comments.
Code comments are at the author's discretion.
Files:
src/configs/sidebar.config.ts
🧠 Learnings (15)
📓 Common learnings
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
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">`.
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Documentation-First Development: Every feature must include comprehensive, user-focused documentation as a first-class deliverable that guides implementation, and all code changes require corresponding documentation updates
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Keep documentation synchronized with product changes
Applied to files:
CLAUDE.md
📚 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:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Applies to **/*.{md,mdx} : All code examples must use `<Tabs syncKey="tech-stack">` format for multi-language SDK samples with all 4 languages (Node.js, Python, Go, Java) for at least 90% of SDK-related snippets
Applied to files:
CLAUDE.md
📚 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: Do not use inconsistent terminology across documentation
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Applies to **/*.{md,mdx} : Use Java variable name `scalekitClient` in all SDK examples
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:47:33.407Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/comment-standards.mdc:0-0
Timestamp: 2026-01-13T12:47:33.407Z
Learning: Applies to **/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy} : Always document public APIs with function/class comments - explain the purpose, parameters, return values, and exceptions; include usage examples for complex functions
Applied to files:
CLAUDE.md
📚 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: Use consistent terminology throughout documentation
Applied to files:
CLAUDE.md
📚 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:
CLAUDE.mdsrc/configs/sidebar.config.ts
📚 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 present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Explain what matters to a developer trying to get work done - use audience-first language in documentation
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Applies to src/configs/sidebar.config.ts : Left Sidebar navigation is configured via `src/configs/sidebar.config.ts`; Secondary Navigation is managed through `src/components/overrides/Header.astro` and `src/components/SecondaryNav.astro`; changes to navigation structure MUST be coordinated across both configurations
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-01-30T18:20:07.851Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:1-6
Timestamp: 2026-01-30T18:20:07.851Z
Learning: In the scalekit-inc/developer-docs repository, MDX files under `src/content/docs/authenticate/fsa/multiapp/` do not use `order` or `tags` fields in their frontmatter. Ordering and grouping are managed centrally in `src/configs/sidebar.config.ts`.
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Applies to src/content/docs/guides/integrations/**/*.mdx : Integration guides located in `src/content/docs/guides/integrations/` MUST be kept synchronized with their index pages at `sso-integrations/index.mdx`, `social-connections/index.mdx`, and `scim-integrations/index.mdx`
Applied to files:
src/configs/sidebar.config.ts
🪛 markdownlint-cli2 (0.21.0)
CLAUDE.md
[warning] 19-19: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🔇 Additional comments (1)
src/configs/sidebar.config.ts (1)
83-83: Good sidebar placement for API keys.Line [83] correctly adds
authenticate/m2m/api-keysunder Add auth to your APIs after the quickstart, which preserves the primary learning path before advanced token lifecycle docs.Based on learnings: "Left Sidebar navigation is configured via
src/configs/sidebar.config.ts; Secondary Navigation is managed throughsrc/components/overrides/Header.astroandsrc/components/SecondaryNav.astro; changes to navigation structure MUST be coordinated across both configurations."
There was a problem hiding this comment.
♻️ Duplicate comments (3)
CLAUDE.md (1)
17-19: 🧹 Nitpick | 🔵 TrivialUse sentence case for heading:
Git commits.Per coding guidelines, all headings must use sentence case. "Commits" is not a proper noun.
✏️ Suggested fix
-### Git Commits +### Git commitsAs per coding guidelines: "Use sentence case for all titles and headings in MD/MDX documentation."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` around lines 17 - 19, Update the markdown heading from "Git Commits" to sentence case "Git commits" in CLAUDE.md; locate the heading text "Git Commits" and change only the capitalization so it reads "Git commits" to conform to the documentation sentence-case guideline.src/content/docs/authenticate/m2m/api-keys.mdx (2)
354-365:⚠️ Potential issue | 🟠 MajorFix Go error handling: check
err != nilbefore accessingresult.The current pattern only checks for
ErrTokenValidationFailed. Iferris non-nil for other reasons (network timeout, transport error), the code falls through and accessesresult.TokenInfo, which may cause a nil pointer dereference.🛠️ Proposed fix
result, err := scalekitClient.Token().ValidateToken(ctx, opaqueToken) -if errors.Is(err, scalekit.ErrTokenValidationFailed) { - // Token is invalid, expired, or revoked - log.Printf("Token validation failed: %v", err) - return +if err != nil { + if errors.Is(err, scalekit.ErrTokenValidationFailed) { + // Token is invalid, expired, or revoked + log.Printf("Token validation failed: %v", err) + } else { + // Network/transport error + log.Printf("Token validation error: %v", err) + } + return } orgId := result.TokenInfo.OrganizationIdThis same fix applies to the other Go validation snippets at lines 436-449 and 525-540.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/m2m/api-keys.mdx` around lines 354 - 365, The code calls scalekitClient.Token().ValidateToken and only checks errors.Is(err, scalekit.ErrTokenValidationFailed) before using result.TokenInfo; update the error handling in ValidateToken call sites (the snippet around ValidateToken, and the other Go validation snippets using the same pattern) to first check if err != nil and handle/return on any non-nil error, then separately check for errors.Is(err, scalekit.ErrTokenValidationFailed) to treat invalid/expired tokens; ensure result is only accessed after confirming err == nil so result.TokenInfo and result.TokenInfo.GetUserId() cannot be dereferenced when result is nil.
979-987: 🧹 Nitpick | 🔵 TrivialConsider adding a "What's next" navigation signal.
The page ends with best practices tips but lacks an explicit navigation pointer to the next page in the M2M authentication journey. Per coding guidelines, every page should end with a clear "what's next" signal — either a
next:frontmatter link, a<LinkCard>, or an explicit paragraph.💡 Example addition
- **Rotate keys safely**: To rotate an API key, create a new key, update the consuming service to use the new key, verify the new key works, then invalidate the old key. This avoids downtime during rotation. You now have everything you need to issue, validate, and manage API keys in your application. +## What's next + +<CardGrid> + <LinkCard + title="M2M authentication quickstart" + description="Learn about JWT-based machine-to-machine authentication" + href="/authenticate/m2m/api-auth-quickstart/" + /> +</CardGrid> + </Steps>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/m2m/api-keys.mdx` around lines 979 - 987, Add an explicit "what's next" navigation pointer to the end of this page by either adding a `next:` frontmatter entry pointing to the next M2M auth doc, inserting a `<LinkCard>` component after the closing paragraph to surface the next topic, or appending a short linking paragraph ("What's next: see ...") that points readers to the next page in the M2M authentication journey; place this immediately after the final sentence ("You now have everything...") so it appears as the final navigation cue.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@CLAUDE.md`:
- Around line 17-19: Update the markdown heading from "Git Commits" to sentence
case "Git commits" in CLAUDE.md; locate the heading text "Git Commits" and
change only the capitalization so it reads "Git commits" to conform to the
documentation sentence-case guideline.
In `@src/content/docs/authenticate/m2m/api-keys.mdx`:
- Around line 354-365: The code calls scalekitClient.Token().ValidateToken and
only checks errors.Is(err, scalekit.ErrTokenValidationFailed) before using
result.TokenInfo; update the error handling in ValidateToken call sites (the
snippet around ValidateToken, and the other Go validation snippets using the
same pattern) to first check if err != nil and handle/return on any non-nil
error, then separately check for errors.Is(err,
scalekit.ErrTokenValidationFailed) to treat invalid/expired tokens; ensure
result is only accessed after confirming err == nil so result.TokenInfo and
result.TokenInfo.GetUserId() cannot be dereferenced when result is nil.
- Around line 979-987: Add an explicit "what's next" navigation pointer to the
end of this page by either adding a `next:` frontmatter entry pointing to the
next M2M auth doc, inserting a `<LinkCard>` component after the closing
paragraph to surface the next topic, or appending a short linking paragraph
("What's next: see ...") that points readers to the next page in the M2M
authentication journey; place this immediately after the final sentence ("You
now have everything...") so it appears as the final navigation cue.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
⛔ Files ignored due to path filters (1)
public/d2/docs/authenticate/m2m/api-keys-0.svgis excluded by!**/*.svg
📒 Files selected for processing (2)
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (5)
**/*.{yml,yaml,md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/browsecentral-labels.mdc)
**/*.{yml,yaml,md,mdx}: BrowseCentral labels should be maximum 3-5 words - keep concise but add context when needed
BrowseCentral labels should be action-oriented - start with verbs when possible
BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
BrowseCentral labels should include specific context when needed (e.g., 'Configure Scalekit MCP server', 'Validate incoming API requests')
BrowseCentral labels should use integration context when applicable (e.g., 'Build MCP auth with your existing auth system')
BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'
Files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/deno-docs-style.mdc)
**/*.{md,mdx}: Use sentence case for all titles and headings in MD/MDX documentation
Keep page titles short and descriptive (3–7 words when possible) in MD/MDX documentation
Use outcome-focused headings that describe results, not categories (e.g., 'Run a script' not 'Scripts')
Avoid gerunds in headings when an imperative works - prefer 'Configure proxies' over 'Configuring proxies'
Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Use sentence case in sidebar labels without punctuation
Set frontmatter title in sentence case with a clear outcome; description in one sentence (≤160 chars); sidebar.label as shorter form of title; enable tableOfContents on longer pages
Start documentation pages with a one-paragraph overview explaining what the page covers and when to use it
Present the primary use case (80% path) first in documentation, with edge cases later
Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Break up long documentation sections with subheadings every 3–6 paragraphs
Use asides for important notes, tips, cautions, and references in documentation
Provide runnable, minimal code examples that work as-is in documentation
Prefer CLI-first examples and show file layout when helpful in documentation
Label code blocks with titles for context (e.g., 'Terminal', 'main.ts') in documentation
Keep code block annotations brief and purposeful - annotate only what matters
Use consistent variable and file names across a documentation page
Use descriptive link text in documentation (e.g., 'See permission flags' not 'click here')
Prefer relative links for internal documentation pages and include anchors for section references
Reference APIs consistently using backticks for code, file names, CLI flags, and endpoints
Use backticks for code, file names, CLI flags, and endpoints in documentation
Use lists for options and features in documentation; tables only when comparisons are cleare...
Files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
CLAUDE.md
⚙️ CodeRabbit configuration file
CLAUDE.md: CLAUDE.md is the quick-reference for AI assistant behavior in this repo.
- It MUST reference
.specify/memory/constitution.mdas the single
source of truth.- SDK variable names section is CRITICAL — any change here must be
intentional and reflected across all code examples in the docs.- The "Quality Checklist" section must end every AI-generated draft
withSTYLE-CHECK: [PASSED | TODO].
Files:
CLAUDE.md
**/*.mdx
📄 CodeRabbit inference engine (.cursorrules)
**/*.mdx: Use clear, descriptive titles that explain the purpose of the document
Include comprehensive descriptions in frontmatter metadata
Organize content with logical heading hierarchy (H2, H3, H4)
Use tableOfContents property in frontmatter when content has multiple sections
Set appropriate sidebar labels for navigation in frontmatter
Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Use second person perspective ('your application', 'you receive', 'you must') in documentation
Keep sentences concise, aiming for under 25 words per sentence
Explain the 'why' in documentation with phrases like 'This prevents CSRF attacks by...' or 'Use this to validate that...'
Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Use future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Write 1-3 opening paragraphs that explain what users will accomplish, provide context about when/why, preview key concepts, and use direct instructional language
Begin introduction sections with a clear statement of what the guide covers and explain the problem being solved
Use collapsible sections in introduction for sequence diagrams, video demonstrations, data models, and JSON examples with appropriate icons
Use numbered format within Steps component:1. ## Titlewith all step content indented with exactly 3 spaces
Use action-oriented headings in step-by-step guides within Steps components
Include code examples in all 4 languages (Node.js, Python, Go, Java) within Steps co...
Files:
src/content/docs/authenticate/m2m/api-keys.mdx
⚙️ CodeRabbit configuration file
**/*.mdx: You are reviewing Scalekit developer documentation written in MDX
(Astro + Starlight framework). Apply ALL of the following checks:Frontmatter
titleMUST be ≤ 60 characters and clearly state what the page does.descriptionMUST be ≤ 160 characters, action-oriented, unique per page.sidebar.labelMUST be present and ≤ 30 characters.sidebar.orderMUST be set on every page that lives inside a section
with siblings, to enforce the journey order in sidebar.config.ts.- Flag any missing
prev/nextlinks on pages that are clearly
part of a sequential flow (e.g., quickstart → implement-login →
complete-login → manage-session → logout).Voice & Style (CLAUDE.md standards)
- Voice: confident, direct, collaborative, instructional.
- Person: second person only ("you", "your application"). Reject "we",
"our", "the developer", "the user".- Tense: present tense for descriptions; imperative mood for instructions.
- Flag weasel words: "simply", "just", "easy", "straightforward",
"obviously", "of course", "note that".- Flag passive voice constructions where active voice is clearer.
- Headings must be sentence case, not Title Case (except proper nouns).
- No heading should end with a colon or period.
Content structure
- How-to guides MUST contain numbered
<Steps>(Starlight component).- Concept pages MUST NOT contain numbered steps — concepts explain, not instruct.
- API reference pages MUST list parameters in a table with Name / Type /
Required / Description columns.- Every page MUST end with a clear "what's next" signal — either a
next:frontmatter link, a<LinkCard>, or an explicit paragraph
pointing the reader forward in the sidebar journey.Code examples
- ALL code examples that show SDK usage MUST include all four language
tabs: Node.js, Python, Go, Java — using<Tabs syncKey="tech-stack">.- SDK variable names are STRICTLY:
scalekit(Node.js),
scalekit_client(Python),scalekitClient(Go), ...
Files:
src/content/docs/authenticate/m2m/api-keys.mdx
src/content/docs/authenticate/**/*.mdx
⚙️ CodeRabbit configuration file
src/content/docs/authenticate/**/*.mdx: This page lives in the primary authentication section.
- If it's a quickstart or step-based guide, it MUST use
<Steps>.- Auth method pages (passwordless, social, SSO, passkeys) MUST include
a brief "when to use this" section before the implementation steps.- Any reference to tokens (idToken, accessToken, refreshToken) MUST
clarify: what it contains, its lifetime, and how to use it securely.- The FSA quickstart (
authenticate/fsa/quickstart.mdx) is the
canonical entry point — no other page should duplicate its 5-step
install→redirect→callback→session→logout structure.
Files:
src/content/docs/authenticate/m2m/api-keys.mdx
🧠 Learnings (55)
📓 Common learnings
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
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">`.
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Documentation-First Development: Every feature must include comprehensive, user-focused documentation as a first-class deliverable that guides implementation, and all code changes require corresponding documentation updates
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:48:26.894Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/ted-docs-philosophy.mdc:0-0
Timestamp: 2026-01-13T12:48:26.894Z
Learning: Applies to **/*.{md,mdx} : Documentation titles and all sentences must follow ted-docs-philosophy principles: write simply and clearly with short, unambiguous sentences; avoid jargon unless necessary; use clear section titles, short paragraphs, topic sentences, and bulleted lists; maintain consistency in style, formatting, and terminology; use imperative mood and right-branching sentences; bold important information; introduce topics broadly and prioritize by value
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Don't skip important context or prerequisites in documentation
Applied to files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:48:23.003Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/sentence-casing-headings.mdc:0-0
Timestamp: 2026-01-13T12:48:23.003Z
Learning: Applies to **/*.{md,mdx} : All headings in documentation files must use sentence casing (only the first word and any proper nouns are capitalized, while the rest is lowercase)
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-26T07:21:32.951Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 448
File: src/content/docs/reference/agent-connectors/googlesheets.mdx:89-131
Timestamp: 2026-02-26T07:21:32.951Z
Learning: In src/content/docs/reference/agent-connectors/** MDX files, tool headings (e.g., `googlesheets_create_spreadsheet`, `googlesheets_get_values`) intentionally use H2 (##) instead of H3 to ensure they appear in the table of contents for easier navigation. This is a deliberate UX choice for agent connector reference pages and should not be flagged as a hierarchy issue.
Applied to files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Maintain proper heading hierarchy and list semantics in documentation for accessibility
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Maintain consistent terminology across documentation pages
Applied to files:
CLAUDE.md
📚 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:
CLAUDE.md
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Keep headings parallel with similar grammatical form within a section in documentation
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Don't use inconsistent terminology across documentation pages
Applied to files:
CLAUDE.md
📚 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:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Applies to **/*.{md,mdx} : Use Node.js variable name `scalekit` in all SDK examples
Applied to files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-10T05:32:59.967Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
Applied to files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Applies to **/*.{md,mdx} : Use Python variable name `scalekit_client` in all SDK examples
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Applies to **/*.{md,mdx} : Use Java variable name `scalekitClient` in all SDK examples
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Applies to **/*.{md,mdx} : Use Go variable name `scalekitClient` in all SDK examples
Applied to files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-25T13:32:58.695Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/quickstart.mdx:47-47
Timestamp: 2026-02-25T13:32:58.695Z
Learning: In Agent Auth documentation (src/content/docs/agent-auth/**/*.mdx), the Node.js SDK installation must use scalekit-sdk/node2.2.0-beta.1 because Agent Auth features are currently only available in the beta version, not in the latest stable release. Do not flag this as an issue or suggest upgrading to stable versions.
Applied to files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 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 present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Applied to files:
CLAUDE.mdsrc/content/docs/authenticate/m2m/api-keys.mdx
📚 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 : Include configuration comments in code examples: '// Get the signing secret from Scalekit dashboard > Interceptors tab'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-30T18:20:07.851Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:1-6
Timestamp: 2026-01-30T18:20:07.851Z
Learning: In the scalekit-inc/developer-docs repository, MDX files under `src/content/docs/authenticate/fsa/multiapp/` do not use `order` or `tags` fields in their frontmatter. Ordering and grouping are managed centrally in `src/configs/sidebar.config.ts`.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 : Include context comments explaining what's happening in code: '// Extract encrypted tokens from request cookies', '// Decrypt the access token before validation'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 : Always include security comments in security-related code with pattern: '// Security: ALWAYS verify requests are from Scalekit before processing'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Applies to src/content/docs/guides/integrations/**/*.mdx : Integration guides located in `src/content/docs/guides/integrations/` MUST be kept synchronized with their index pages at `sso-integrations/index.mdx`, `social-connections/index.mdx`, and `scim-integrations/index.mdx`
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 : Always include error handling in code examples showing both success and error paths
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Applies to **/*.{md,mdx} : All code examples must include imports (collapsible if noisy), realistic data, success and error paths with security comments stating the threat, why the pattern is required, and what can go wrong if omitted
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-26T07:20:42.107Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 448
File: src/content/docs/reference/agent-connectors/googlemeet.mdx:1-87
Timestamp: 2026-02-26T07:20:42.107Z
Learning: For auto-generated agent connector documentation pages in src/content/docs/reference/agent-connectors/, the "what's next" signal requirement (next: frontmatter link, <LinkCard>, or concluding paragraph) does not apply. These are reference pages generated by scripts/sync-agent-connectors.js and serve as lookup resources rather than sequential guides.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 : Include todo/next step comments in code examples: '// TODO: Store user session (next guide covers this)', '// Next step: Create a session and log in the user'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Use sentence case in sidebar labels without punctuation
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Use sentence case for headings near code examples (e.g., 'Authenticate users')
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should be action-oriented - start with verbs when possible
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Set frontmatter title in sentence case with a clear outcome; description in one sentence (≤160 chars); sidebar.label as shorter form of title; enable tableOfContents on longer pages
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Set concise sidebar labels that match user vocabulary in navigation metadata
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 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 action-oriented headings in step-by-step guides within Steps components
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Use sequential steps with verification checks for procedures in documentation
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.mdx : Use Steps component for sequential instructions in MDX documentation
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-25T18:40:05.343Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.343Z
Learning: Journey-Focused Documentation: Product-based documentation (MCP Auth, Agent Auth, Full Stack Auth, Modular SCIM, Modular SSO) MUST follow a journey-focused approach representing a developer's journey toward implementing authentication
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-18T18:25:59.260Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 438
File: CONTRIBUTING.md:1-7
Timestamp: 2026-02-18T18:25:59.260Z
Learning: In scalekit-inc/developer-docs, root-level markdown files like CONTRIBUTING.md and README.md are standard GitHub repository files and do not require frontmatter. Only MDX files under src/content/docs/ that are processed by the Starlight docs system need frontmatter with title, description, and navigation metadata.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-25T13:04:27.491Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:9-17
Timestamp: 2026-02-25T13:04:27.491Z
Learning: Allow page-level CSS overrides in MDX frontmatter (head: style) for readability and engagement, even if it customizes typography beyond defaults. This applies to per-page UX decisions, including heading sizes and style tweaks, but keep overrides purposeful, accessible, and within the repository's design guidelines. Use these overrides sparingly and document the rationale for maintainability.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Don't assume reader knowledge of advanced concepts in documentation
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Use Expressive Code consistently across all documentation pages, preferring Starlight's `<Code>` component for rich features (titles, markers, accurate syntax highlighting) and dynamic snippets over fenced code blocks
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-04T12:47:16.544Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 412
File: src/content/docs/dev-kit/tools/scalekit-dryrun.mdx:1-23
Timestamp: 2026-02-04T12:47:16.544Z
Learning: In scalekit-inc/developer-docs, the MDX frontmatter field order is required only when the sidebar configuration points to a directory (for auto-generation). If the sidebar.config.ts references a specific file path, the order field is not required. Apply this check to all MDX files under src/content/docs: if a file contributes to an auto-generated sidebar (directory path), ensure order is present; if it’s linked to a concrete file, order can be omitted. Use sidebar.config.ts to determine whether a given MDX file falls under directory-based vs file-specific sidebar references.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-01-30T18:18:50.883Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx:31-49
Timestamp: 2026-01-30T18:18:50.883Z
Learning: In all Scalekit documentation files (MDX), treat the terms 'Applications', 'Single Page Application (SPA)', 'Native Application', and 'Web Application' as proper nouns and preserve their capitalization in headings and body text. Ensure these terms remain capitalized even when used in sentence case or within prose.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-25T08:57:12.201Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/quickstart.mdx:2-10
Timestamp: 2026-02-25T08:57:12.201Z
Learning: In Scalekit developer-docs (Astro Starlight), do not auto-suggest adding tableOfContents in frontmatter unless the user explicitly overrides the default behavior. The default enables tableOfContents with minHeadingLevel 2 and maxHeadingLevel 3. Only set tableOfContents when you want to customize heading levels or disable it entirely; otherwise omit it for other docs.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-25T03:34:41.147Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:31-31
Timestamp: 2026-02-25T03:34:41.147Z
Learning: In MDX files, import { Code } from 'astrojs/starlight/components' only if the MDX content actually uses the <Code> component. If the file uses only fenced code blocks (```), the import is not required. Apply this guideline to all MDX files (e.g., src/content/docs/**/*.mdx) to avoid unnecessary imports and reduce bundle size.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
📚 Learning: 2026-02-25T18:41:00.639Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 446
File: src/content/docs/authenticate/m2m/api-auth-quickstart.mdx:78-78
Timestamp: 2026-02-25T18:41:00.639Z
Learning: Preserve full URLs inside code comments in MDX code blocks (bash/python/js) when the URLs are part of copyable examples. Do not flag these in code examples. Use relative paths in prose and hyperlinks within MDX; only enforce relative paths for markdown prose links, not for URLs inside code comments.
Applied to files:
src/content/docs/authenticate/m2m/api-keys.mdx
🔇 Additional comments (6)
src/content/docs/authenticate/m2m/api-keys.mdx (4)
1-6: LGTM — Frontmatter is well-structured.The frontmatter complies with all requirements: title (8 chars ≤ 60), description (108 chars ≤ 160), and sidebar label in sentence case.
25-43: LGTM — Sequence diagram is clear and accurate.The D2 diagram effectively illustrates the API key flow from creation through validation.
59-113: LGTM — SDK initialization examples are complete and correct.All four language tabs use the correct SDK variable names (
scalekit,scalekit_client,scalekitClient,scalekitClient) and include proper environment variable handling for credentials.
870-911: LGTM — Go middleware example demonstrates correct error handling.This implementation properly checks
err != nilfirst, then differentiates between validation failures (401) and transport/internal errors (500). The earlier Go validation snippets should follow this same pattern.CLAUDE.md (2)
21-28: LGTM — SDK variable names section is properly structured.The critical SDK variable naming conventions are now clearly documented with appropriate emphasis. This resolves the previous content mismatch issue.
13-15: LGTM — Documentation-first section now has correct heading case and content.The heading uses proper sentence case, and the content correctly describes the documentation-first development principle. This addresses the previous review feedback about heading/content mismatch.
2 participants
Summary
authenticate/m2m/api-keys.mdx) covering create, validate, list, and invalidate token operations with examples across all 4 SDKs (Node.js, Python, Go, Java)authenticate/m2m/api-auth-quickstart.mdx) with OAuth 2.0 terminology, clearer structure, and improved code examples/guides/m2m/scopes/→/authenticate/m2m/api-auth-quickstart/and/reference/api/m2m-clients→/guides/m2m/api-auth-m2m-clients/guides/m2m/scopes.mdxpage (content merged into M2M quickstart)Test plan
pnpm --filter scalekit-docs build— no errors/authenticate/m2m/api-keysrenders correctlySummary by CodeRabbit