Skip to content

docs: Update README with agent-first positioning #140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
saif-at-scalekit wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: Update README with agent-first positioning #140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6583518
docs: Update README with agent-first positioning and improved structure
saif-at-scalekit Mar 30, 2026
8ff860d
fix: correct SDK class name, capitalization, cookie security, and mar…
saif-at-scalekit Apr 1, 2026
ec504d6
Merge branch 'main' into docs/update-readme-agent-first
Apr 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
243 changes: 112 additions & 131 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,164 +1,145 @@
<p align="left">
<a href="https://scalekit.com" target="_blank" rel="noopener noreferrer">
<picture>
<img src="https://cdn.scalekit.cloud/v1/scalekit-logo-dark.svg" height="64">
</picture>
</a>
<br/>
</p>

# Official Python SDK

[![PyPI version](https://img.shields.io/pypi/v/scalekit-sdk-python.svg?style=flat-square)](https://pypi.org/project/scalekit-sdk-python/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python versions](https://img.shields.io/pypi/pyversions/scalekit-sdk-python.svg?style=flat-square)](https://pypi.org/project/scalekit-sdk-python/)

<a href="https://scalekit.com" target="_blank" rel="noopener noreferrer">Scalekit</a> is the **auth stack for AI apps** - from human authentication to agent authorization. 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 Python SDK enables both traditional B2B authentication and cutting-edge agentic workflows.
<div align="center">

## 🤖 Agent-First Features
<a href="https://scalekit.com" target="_blank" rel="noopener noreferrer">
<picture>
<img src="./images/scalekit.jpg" alt="Scalekit" height="64">

@coderabbitai coderabbitai Bot Apr 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify logo assets and README references.
set -euo pipefail

echo "== README image references =="
rg -n '\<img\s+src=' README.md

echo
echo "== Image files in repo (case-insensitive) =="
fd -i 'scalekit.*\.(svg|png|jpg|jpeg|webp)$' .

echo
echo "== Files under images/ =="
fd . images -t f || true

Repository: scalekit-inc/scalekit-sdk-python

Length of output: 201

🏁 Script executed:

#!/bin/bash
# Verify logo assets and README references (corrected)
set -euo pipefail

echo "== README image references =="
rg 'img.*src=' README.md || echo "No matches found"

echo
echo "== Image files in repo (case-insensitive) =="
fd -i 'scalekit.*\.(svg|png|jpg|jpeg|webp)$' . || echo "No matching image files found"

echo
echo "== Files under images/ directory =="
if [ -d images ]; then
    fd . images -t f
    echo "Directory exists"
else
    echo "images/ directory does not exist"
fi

echo
echo "== README.md first 20 lines =="
head -20 README.md || echo "README.md not found"

Repository: scalekit-inc/scalekit-sdk-python

Length of output: 1376

Confirm whether README should reference the SVG logo or the JPG file.

The referenced JPG file at ./images/scalekit.jpg exists and is correctly linked in README. However, an SVG file (scalekit-logo.svg) also exists at the repository root. If the PR objective was to add an SVG logo asset, the README should likely reference that instead, or the SVG should be moved to the images/ directory for consistency.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 5, Decide which logo file to use and make README
consistent: either update README's image reference (replace
./images/scalekit.jpg with ./scalekit-logo.svg) if you intend to use the SVG at
repo root, or move scalekit-logo.svg into the images/ folder and keep the README
referencing ./images/scalekit.jpg (or replace the JPG with
./images/scalekit-logo.svg). Ensure the README image src, alt text ("Scalekit"),
and sizing (height="64") are updated to match the chosen file name (scalekit.jpg
or scalekit-logo.svg) and that the referenced file actually exists in that path.

</picture>
</a>

- **🔐 Agent Identity**: Agents as first-class actors with human ownership and org context
- **🎯 MCP-Native OAuth 2.1**: Purpose-built for Model Context Protocol with DCR/PKCE support
- **⏰ Ephemeral Credentials**: Time-bound, task-based authorization (minutes, not days)
- **🔒 Token Vault**: Per-user, per-tool token storage with rotation and progressive consent
- **👥 Human-in-the-Loop**: Step-up authentication when risk crosses thresholds
- **📊 Immutable Audit**: Track which user initiated, which agent acted, what resource was accessed
<p><strong>Official Python SDK for Scalekit — the auth stack for agents.</strong><br>
authentication, authorization, and tool-calling for human-in-the-loop and autonomous agent flows.</p>

## 👨‍💼 Human Authentication
[![PyPI version](https://img.shields.io/pypi/v/scalekit-sdk-python.svg)](https://pypi.org/project/scalekit-sdk-python/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python versions](https://img.shields.io/pypi/pyversions/scalekit-sdk-python.svg)](https://pypi.org/project/scalekit-sdk-python)

- **🔐 Enterprise SSO**: Support for SAML and OIDC protocols
- **👥 SCIM Provisioning**: Automated user provisioning and deprovisioning
- **🚀 Passwordless Authentication**: Magic links, OTP, and modern auth flows
- **🏢 Multi-tenant Architecture**: Organization-level authentication policies
- **📱 Social Logins**: Support for popular social identity providers
- **🛡️ Full-Stack Auth**: Complete IdP-of-record solution for B2B SaaS
- **🐍 Pythonic API**: Clean, intuitive interface following Python conventions
**[📖 Documentation](https://docs.scalekit.com)** · **[🐛 Report an Issue](https://github.com/scalekit-inc/scalekit-sdk-python/issues)** · **[💬 Join our Slack](https://join.slack.com/t/scalekit-community/shared_invite/zt-3gsxwr4hc-0tvhwT2b_qgVSIZQBQCWRw)**

<div>
📚 <a target="_blank" href="https://docs.scalekit.com">Documentation</a> • 🚀 <a target="_blank" href="https://docs.scalekit.com/sso/quickstart/">SSO Quickstart</a> • 💻 <a target="_blank" href="https://docs.scalekit.com/apis">API Reference</a>
</div>
<hr />

## Pre-requisites

1. [Sign up](https://scalekit.com) for a Scalekit account.
2. Get your ```env_url```, ```client_id``` and ```client_secret``` from the Scalekit dashboard.

## Installation

Install Scalekit SDK using your preferred package manager.

---

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 Python SDK enables both traditional B2B authentication and cutting-edge agentic workflows.
Comment on lines +22 to +23

@coderabbitai coderabbitai Bot Apr 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix intro sentence grammar/capitalization for clarity.

The opening sentence starts with lowercase and has awkward punctuation (Scalekit](...), —). Clean this up to keep the README polished.

Suggested edit 
-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` around lines 22 - 23, Fix the README intro sentence by
capitalizing the first word and removing the awkward punctuation around the
Scalekit link: replace the phrase beginning "this is the official Python SDK for
[Scalekit](...)," (which contains "Scalekit](...), —") with a clean sentence
like "This is the official Python SDK for Scalekit — the auth stack for agents."
Ensure the em-dash is correctly placed (no stray comma) and preserve the
following sentence "This Python SDK enables both traditional B2B authentication
and cutting-edge agentic workflows." to keep flow and clarity.

#### Agent-First Features
- **Agent Identity** — Agents as first-class actors with human ownership and org context
- **MCP-Native OAuth 2.1** — Purpose-built for Model Context Protocol with DCR/PKCE support
- **Ephemeral Credentials** — Time-bound, task-based authorization (minutes, not days)
- **Token Vault** — per-user, per-tool token storage with rotation and progressive consent
- **Human-in-the-Loop** — step-up authentication when risk crosses thresholds
- **Immutable Audit** — track which user initiated, which agent acted, what resource was accessed
#### Human Authentication
- **Enterprise SSO** — support for SAML and OIDC protocols
- **SCIM Provisioning** — automated user provisioning and deprovisioning
- **Passwordless Authentication** — magic links, OTP, and modern auth flows
- **Multi-tenant Architecture** — organization-level authentication policies
- **Social Logins** — support for popular social identity providers
- **Full-Stack Auth** — complete IdP-of-record solution for B2B SaaS
- **Pythonic API** — idiomatic Python with clean, intuitive interfaces
---
### Getting started
#### Prerequisites
- **Python** ≥ 3.8
- [Scalekit account](https://scalekit.com) with `env_url`, `client_id`, and `client_secret`
#### Installation
```sh
pip install scalekit-sdk-python

# or
poetry add scalekit-sdk-python
```

## Usage

```py

#### Usage
```python
from scalekit import ScalekitClient

sc = ScalekitClient(
env_url,
client_id,
client_secret
scalekit_client = ScalekitClient(
client_id="your-client-id",
client_secret="your-client-secret",
env_url="https://your-env.scalekit.com"
)

# Use the sc object to interact with the Scalekit API
auth_url = sc.get_authorization_url(
"https://acme-corp.com/redirect-uri",
state="state",
connection_id="con_123456789"
# use scalekit_client to interact with the Scalekit API
auth_url = scalekit_client.get_authorization_url(
"https://acme-corp.com/redirect-uri",
state="state",
connection_id="con_123456789"
)

```

##### Minimum Requirements

To use the Scalekit Python SDK, you must have the following:

| Component | Version |
| --------- | ------- |
| Python | 3.8+ |

> **Tip:** Although Python 3.8 meets the minimum requirement, using a more recent version (such as Python 3.9 or later) is advisable.


## Examples - SSO with FastAPI

Below is a simple code sample that showcases how to implement Single Sign-on using Scalekit SDK

```py
---
### Example — SSO with FastAPI
```python
from fastapi import FastAPI, Request, Response
from scalekit import ScalekitClient
import uvicorn

app = FastAPI()

sc = ScalekitClient(
env_url,
client_id,
client_secret
scalekit_client = ScalekitClient(
env_url="https://your-env.scalekit.com",
client_id="your-client-id",
client_secret="your-client-secret"
)

redirect_uri = "http://localhost:8000/auth/callback"

@app.get("/auth/login")
async def auth_login(request: Request):
auth_url = sc.get_authorization_url(
redirect_uri,
state="state",
connection_id="con_123456789"
)
return Response(status_code=302, headers={"Location": auth_url})

auth_url = scalekit_client.get_authorization_url(
redirect_uri,
state="state",
connection_id="con_123456789"
)
return Response(status_code=302, headers={"Location": auth_url})
@app.get("/auth/callback")
async def auth_callback(request: Request):
code = request.query_params.get("code")
token = sc.authenticate_with_code(
code,
redirect_uri
)
response = JSONResponse(content=token)
response.set_cookie("access_token", token["access_token"])

return response

code = request.query_params.get("code")
token = scalekit_client.authenticate_with_code(code, redirect_uri)
response = Response(content="Authenticated successfully")
response.set_cookie(
"access_token",
token["access_token"],
httponly=True,
secure=True,
samesite="Lax"
)
return response
if __name__ == "__main__":
uvicorn.run(app, port=8080)

import uvicorn
uvicorn.run(app, port=8080)
```
```

@coderabbitai coderabbitai Bot Apr 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Remove the stray fenced code delimiter at Line 106.

There is an extra triple-backtick after the FastAPI snippet. This can break Markdown rendering for the following sections.

Proposed fix 
@@
-```
</details>

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.22.0)</summary>

[warning] 106-106: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @README.md at line 106, Remove the stray triple-backtick fence that follows
the FastAPI code snippet (the extra closing delimiter) so the Markdown renders correctly; locate the trailing fenced code delimiter that appears immediately after the FastAPI example and delete that lone line so the code
block is properly terminated only once.


</details>

<!-- fingerprinting:phantom:triton:hawk:871a2b5e-49a0-4308-a849-e4aecc08311d -->

<!-- This is an auto-generated comment by CodeRabbit -->


## 📱 Example Apps

Explore fully functional sample applications built with popular Python frameworks and the Scalekit SDK:

| Framework | Repository | Description |
|-----------|------------|-------------|
| **FastAPI** | [scalekit-fastapi-example](https://github.com/scalekit-developers/scalekit-fastapi-example) | Modern async Python API framework |

## 🔗 Helpful Links

### 📖 Quickstart Guides
- [**SSO Integration**](https://docs.scalekit.com/sso/quickstart/) - Implement enterprise Single Sign-on
- [**Full Stack Auth**](https://docs.scalekit.com/fsa/quickstart/) - Complete authentication solution
- [**Passwordless Auth**](https://docs.scalekit.com/passwordless/quickstart/) - Modern authentication flows
- [**Social Logins**](https://docs.scalekit.com/social-logins/quickstart/) - Popular social identity providers
- [**Machine-to-Machine**](https://docs.scalekit.com/m2m/quickstart/) - API authentication

### 📚 Documentation & Reference
- [**API Reference**](https://docs.scalekit.com/apis) - Complete API documentation
- [**Developer Kit**](https://docs.scalekit.com/dev-kit/) - Tools and utilities
- [**API Authentication Guide**](https://docs.scalekit.com/guides/authenticate-scalekit-api/) - Secure API access

### 🛠️ Additional Resources
- [**Setup Guide**](https://docs.scalekit.com/guides/setup-scalekit/) - Initial platform configuration
- [**Code Examples**](https://docs.scalekit.com/directory/code-examples/) - Ready-to-use code snippets
- [**Admin Portal Guide**](https://docs.scalekit.com/directory/guides/admin-portal/) - Administrative interface
- [**Launch Checklist**](https://docs.scalekit.com/directory/guides/launch-checklist/) - Pre-production checklist

## License

This project is licensed under the **MIT license**.
See the [LICENSE](LICENSE) file for more information.
| **Django** | [scalekit-django-auth-example](https://github.com/scalekit-inc/scalekit-django-auth-example) | Django web framework integration |
| **Flask** | [scalekit-flask-auth-example](https://github.com/scalekit-inc/scalekit-flask-auth-example) | Flask microframework integration |

---
Comment thread
coderabbitai[bot] marked this conversation as resolved.
### Helpful links
#### Quickstart Guides
- [SSO Integration](https://docs.scalekit.com/sso/quickstart/) — implement enterprise Single Sign-on
- [Full Stack Auth](https://docs.scalekit.com/fsa/quickstart/) — complete authentication solution
- [Passwordless Auth](https://docs.scalekit.com/passwordless/quickstart/) — modern authentication flows
- [Social Logins](https://docs.scalekit.com/social-logins/quickstart/) — popular social identity providers
- [Machine-to-Machine](https://docs.scalekit.com/m2m/quickstart/) — API authentication
#### Documentation & Reference
- [API Reference](https://docs.scalekit.com/apis) — complete API documentation
- [Developer Kit](https://docs.scalekit.com/dev-kit/) — tools and utilities
- [API authentication guide](https://docs.scalekit.com/guides/authenticate-scalekit-api/) — secure API access
#### Additional resources
- [Setup Guide](https://docs.scalekit.com/guides/setup-scalekit/) — initial platform configuration
- [Code examples](https://docs.scalekit.com/directory/code-examples/) — ready-to-use code snippets
- [Admin Portal Guide](https://docs.scalekit.com/directory/guides/admin-portal/) — administrative interface
- [Launch Checklist](https://docs.scalekit.com/directory/guides/launch-checklist/) — pre-production checklist
---
### Contributing

Contributions are welcome! Coming soon: contribution guidelines.

For now:
1. Fork this repository
2. Create a branch — `git checkout -b fix/my-improvement`
3. Make your changes
4. Run tests — `pytest`
5. Open a Pull Request

---
### License
This project is licensed under the **MIT license**. See the [LICENSE](LICENSE) file for more information.
Binary file added images/scalekit.jpg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
13 changes: 13 additions & 0 deletions scalekit-logo.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading