docs: add REFERENCE.md for API Tokens, Tools, and Actions#139
docs: add REFERENCE.md for API Tokens, Tools, and Actions#139saif-at-scalekit wants to merge 3 commits into
Conversation
- Add API Tokens section (5 methods) - Add Tools section (3 methods) - Add Actions/Connect section (13 methods) - Add Actions MCP subsection (11 methods) - All methods documented following existing REFERENCE.md style
saif-at-scalekit
requested review from
Avinash-Kamath and
jranaskit
as code owners
WalkthroughAdded extensive autogenerated documentation to Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant ActionsSvc as Actions Service
participant ToolExec as Tool Executor
participant ConnAcct as Connected Account
participant ExternalAPI as External API
Client->>ActionsSvc: execute_tool(tool_name, identifier, params?, connected_account_id?)
ActionsSvc->>ConnAcct: resolve connected_account_id (if provided)
ConnAcct-->>ActionsSvc: auth/credentials
ActionsSvc->>ToolExec: invoke tool with params + credentials
ToolExec->>ExternalAPI: request (using tool-specific protocol)
ExternalAPI-->>ToolExec: response
ToolExec-->>ActionsSvc: tool execution result
ActionsSvc-->>Client: ExecuteToolResponse
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 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.
🧹 Nitpick comments (1)
REFERENCE.md (1)
7801-7801: Consider hyphenating compound adjective.For improved grammar, consider changing "Human readable name" to "Human-readable name" since "human-readable" functions as a compound adjective modifying "name".
✍️ Optional grammar improvement
-**name:** `str` - Human readable name for the configuration +**name:** `str` - Human-readable name for the configuration🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@REFERENCE.md` at line 7801, Update the documentation entry for the field "name" (type `str`) to use a hyphenated compound adjective: change "Human readable name for the configuration" to "Human-readable name for the configuration" so the phrase correctly modifies "name".
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@REFERENCE.md`:
- Line 7801: Update the documentation entry for the field "name" (type `str`) to
use a hyphenated compound adjective: change "Human readable name for the
configuration" to "Human-readable name for the configuration" so the phrase
correctly modifies "name".
- Refactor README structure for better readability - Add agent-first features section ahead of human auth - Update messaging to emphasize 'auth stack for agents' positioning - Add scalekit-logo.svg asset for consistent branding - Improve documentation links and quick start section - Align features description with current capabilities
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (3)
README.md (3)
99-100: Add blank line before table for markdown compliance.Markdown best practices suggest surrounding tables with blank lines for better rendering and compatibility.
📋 Proposed fix
uvicorn.run(app, port=8080)
| Framework | Repository | Description |
</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@README.mdaround lines 99 - 100, The markdown table header line "| Framework
| Repository | Description |" needs a blank line immediately before it to
satisfy Markdown rendering rules; edit the README to insert a single empty line
above that table header (i.e., add a newline before the line containing "|
Framework | Repository | Description |") so the table is properly separated from
the preceding paragraph or block.</details> --- `104-105`: **Add blank line after table for markdown compliance.** Markdown best practices suggest surrounding tables with blank lines for better rendering and compatibility. <details> <summary>📋 Proposed fix</summary> ```diff | **Flask** | [scalekit-flask-auth-example](https://github.com/scalekit-inc/scalekit-flask-auth-example) | Flask microframework integration | + ---🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 104 - 105, The markdown table row for Flask ("| **Flask** | [scalekit-flask-auth-example](https://github.com/scalekit-inc/scalekit-flask-auth-example) | Flask microframework integration |") needs a blank line after the table block to satisfy markdown rendering; edit README.md to insert a single empty line immediately after the table (i.e., after the last table row/closing separator) so the following content is separated from the table.
26-26: Use consistent casing for protocol/standard acronyms.The acronyms "Mcp" and "Dcr/pkce" should use standard uppercase conventions: "MCP" (Model Context Protocol), "DCR" (Dynamic Client Registration), and "PKCE" (Proof Key for Code Exchange).
📝 Proposed fix
-- **Mcp-Native OAuth 2.1** — Purpose-built for Model Context Protocol with Dcr/pkce support +- **MCP-Native OAuth 2.1** — Purpose-built for Model Context Protocol with DCR/PKCE support🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 26, Replace inconsistent acronym casing in the README: change the phrase "Mcp-Native OAuth 2.1" to "MCP-Native OAuth 2.1" and change "Dcr/pkce" to "DCR/PKCE" wherever they appear (specifically update the occurrences of the strings "Mcp-Native OAuth 2.1" and "Dcr/pkce" to use standard uppercase acronyms).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Line 22: The opening sentence in README.md ("this is the official Python SDK
for [Scalekit]...") starts with a lowercase "this"; update that sentence to
capitalize the first word to "This" so the README's first sentence reads
correctly, e.g., change the phrase "this is the official Python SDK for
[Scalekit]" to "This is the official Python SDK for [Scalekit]".
- Around line 71-78: The example imports/instantiates the wrong class: replace
the usage of Scalekit with the actual exported class ScalekitClient (i.e.,
import ScalekitClient and call ScalekitClient(...)) so the example runs without
ImportError; keep the env_url parameter as-is and leave the variable name
scalekit_client unchanged.
- Line 5: The img element for the logo is missing alt text; update the <img
src="https://cdn.scalekit.cloud/v1/scalekit-logo-dark.svg" height="64"> tag to
include a meaningful alt attribute (for example alt="Scalekit logo") so screen
readers can describe the image and improve accessibility.
- Around line 52-58: Update the README example to import and instantiate the
correct exported class and constructor parameter: replace the import of Scalekit
with ScalekitClient and pass env_url instead of environment_url when calling the
constructor (reference symbols: ScalekitClient and env_url) so the example
matches the actual API and avoids ImportError/TypeError.
---
Nitpick comments:
In `@README.md`:
- Around line 99-100: The markdown table header line "| Framework | Repository |
Description |" needs a blank line immediately before it to satisfy Markdown
rendering rules; edit the README to insert a single empty line above that table
header (i.e., add a newline before the line containing "| Framework | Repository
| Description |") so the table is properly separated from the preceding
paragraph or block.
- Around line 104-105: The markdown table row for Flask ("| **Flask** |
[scalekit-flask-auth-example](https://github.com/scalekit-inc/scalekit-flask-auth-example)
| Flask microframework integration |") needs a blank line after the table block
to satisfy markdown rendering; edit README.md to insert a single empty line
immediately after the table (i.e., after the last table row/closing separator)
so the following content is separated from the table.
- Line 26: Replace inconsistent acronym casing in the README: change the phrase
"Mcp-Native OAuth 2.1" to "MCP-Native OAuth 2.1" and change "Dcr/pkce" to
"DCR/PKCE" wherever they appear (specifically update the occurrences of the
strings "Mcp-Native OAuth 2.1" and "Dcr/pkce" to use standard uppercase
acronyms).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 281da3c9-b8de-47a4-820a-e9d147662d52
⛔ Files ignored due to path filters (1)
scalekit-logo.svgis excluded by!**/*.svg
📒 Files selected for processing (1)
README.md
| # Official Python SDK | ||
| <a href="https://scalekit.com" target="_blank" rel="noopener noreferrer"> | ||
| <picture> | ||
| <img src="https://cdn.scalekit.cloud/v1/scalekit-logo-dark.svg" height="64"> |
There was a problem hiding this comment.
Add alt text to the logo image for accessibility.
The logo image is missing alt text, which is important for screen readers and accessibility.
♿ Proposed fix to add alt text
<picture>
- <img src="https://cdn.scalekit.cloud/v1/scalekit-logo-dark.svg" height="64">
+ <img src="https://cdn.scalekit.cloud/v1/scalekit-logo-dark.svg" alt="Scalekit Logo" height="64">
</picture>📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <img src="https://cdn.scalekit.cloud/v1/scalekit-logo-dark.svg" height="64"> | |
| <picture> | |
| <img src="https://cdn.scalekit.cloud/v1/scalekit-logo-dark.svg" alt="Scalekit Logo" height="64"> | |
| </picture> |
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 5-5: Images should have alternate text (alt text)
(MD045, no-alt-text)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` at line 5, The img element for the logo is missing alt text;
update the <img src="https://cdn.scalekit.cloud/v1/scalekit-logo-dark.svg"
height="64"> tag to include a meaningful alt attribute (for example
alt="Scalekit logo") so screen readers can describe the image and improve
accessibility.
|
|
||
| --- | ||
|
|
||
| this is the official Python SDK for [Scalekit](https://scalekit.com), — the auth stack for agents. Build secure AI products faster with authentication for humans (SSO, passwordless, full-stack auth) and agents (Mcp/APIs, delegated actions), all unified on one platform. |
There was a problem hiding this comment.
Capitalize the first word of the sentence.
The sentence begins with a lowercase "this" which is grammatically incorrect.
📝 Proposed fix
-this is the official Python SDK for [Scalekit](https://scalekit.com), — the auth stack for agents. Build secure AI products faster with authentication for humans (SSO, passwordless, full-stack auth) and agents (Mcp/APIs, delegated actions), all unified on one platform.
+This is the official Python SDK for [Scalekit](https://scalekit.com) — the auth stack for agents. Build secure AI products faster with authentication for humans (SSO, passwordless, full-stack auth) and agents (MCP/APIs, delegated actions), all unified on one platform.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| this is the official Python SDK for [Scalekit](https://scalekit.com), — the auth stack for agents. Build secure AI products faster with authentication for humans (SSO, passwordless, full-stack auth) and agents (Mcp/APIs, delegated actions), all unified on one platform. | |
| This is the official Python SDK for [Scalekit](https://scalekit.com) — the auth stack for agents. Build secure AI products faster with authentication for humans (SSO, passwordless, full-stack auth) and agents (MCP/APIs, delegated actions), all unified on one platform. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` at line 22, The opening sentence in README.md ("this is the
official Python SDK for [Scalekit]...") starts with a lowercase "this"; update
that sentence to capitalize the first word to "This" so the README's first
sentence reads correctly, e.g., change the phrase "this is the official Python
SDK for [Scalekit]" to "This is the official Python SDK for [Scalekit]".
| from scalekit import Scalekit | ||
|
|
||
| scalekit_client = Scalekit( | ||
| client_id="your-client-id", | ||
| client_secret="your-client-secret", | ||
| environment_url="https://your-env.scalekit.com" | ||
| ) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the exported class and constructor signature
echo "=== Checking __init__.py exports ==="
rg -n "^__all__" scalekit/__init__.py
echo -e "\n=== Checking ScalekitClient constructor ==="
ast-grep --pattern 'class ScalekitClient:
$$$
def __init__($$$):
$$$'Repository: scalekit-inc/scalekit-sdk-python
Length of output: 32535
Fix incorrect import and constructor parameters in README example.
The README imports and instantiates Scalekit, but the exported class is ScalekitClient. Additionally, the constructor parameter is env_url, not environment_url. Users following this example will encounter ImportError: cannot import name 'Scalekit' and TypeError: got an unexpected keyword argument 'environment_url'.
Proposed fix
-from scalekit import Scalekit
+from scalekit import ScalekitClient
-scalekit_client = Scalekit(
+scalekit_client = ScalekitClient(
+ env_url="https://your-env.scalekit.com",
client_id="your-client-id",
client_secret="your-client-secret",
- environment_url="https://your-env.scalekit.com"
)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 52 - 58, Update the README example to import and
instantiate the correct exported class and constructor parameter: replace the
import of Scalekit with ScalekitClient and pass env_url instead of
environment_url when calling the constructor (reference symbols: ScalekitClient
and env_url) so the example matches the actual API and avoids
ImportError/TypeError.
| from scalekit import Scalekit | ||
|
|
||
| app = FastAPI() | ||
|
|
||
| sc = ScalekitClient( | ||
| env_url, | ||
| client_id, | ||
| client_secret | ||
| scalekit_client = Scalekit( | ||
| env_url="https://your-env.scalekit.com", | ||
| client_id="your-client-id", | ||
| client_secret="your-client-secret" | ||
| ) |
There was a problem hiding this comment.
Critical: Incorrect import and class name (same issue as Getting Started section).
The FastAPI example has the same critical error: importing and using Scalekit instead of the actual exported class ScalekitClient. This will cause an ImportError when users try to run this example.
Note: This example correctly uses env_url as the parameter name (unlike the previous example), but the class name is still wrong.
🐛 Proposed fix
-from scalekit import Scalekit
+from scalekit import ScalekitClient
-scalekit_client = Scalekit(
+scalekit_client = ScalekitClient(
env_url="https://your-env.scalekit.com",
client_id="your-client-id",
client_secret="your-client-secret"
)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| from scalekit import Scalekit | |
| app = FastAPI() | |
| sc = ScalekitClient( | |
| env_url, | |
| client_id, | |
| client_secret | |
| scalekit_client = Scalekit( | |
| env_url="https://your-env.scalekit.com", | |
| client_id="your-client-id", | |
| client_secret="your-client-secret" | |
| ) | |
| from scalekit import ScalekitClient | |
| app = FastAPI() | |
| scalekit_client = ScalekitClient( | |
| env_url="https://your-env.scalekit.com", | |
| client_id="your-client-id", | |
| client_secret="your-client-secret" | |
| ) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 71 - 78, The example imports/instantiates the wrong
class: replace the usage of Scalekit with the actual exported class
ScalekitClient (i.e., import ScalekitClient and call ScalekitClient(...)) so the
example runs without ImportError; keep the env_url parameter as-is and leave the
variable name scalekit_client unchanged.
3 participants
Summary
Adds reference documentation for APIs that existed in the SDK but were not covered in
REFERENCE.md:client.tokens) — create, validate, invalidate, update, and list tokensclient.tools) — list, list scoped, and execute toolsclient.actions/client.connect) — tool execution, connected accounts, modifiers, proxied requests, and account helpersclient.actions.mcp) — MCP config and instance lifecycle plus auth stateNotes
details/ description / usage / parameters pattern inREFERENCE.md.Summary by CodeRabbit