Skip to content

docs(signal): clarify BYOA login validity and handoff timeout #927

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

Merged
saif-at-scalekit merged 2 commits into from
Aug 14, 2026
Merged

docs(signal): clarify BYOA login validity and handoff timeout #927

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5c59705
docs(signal): clarify BYOA login validity and handoff timeout
claude Aug 3, 2026
fd94a43
docs(signal): address CodeRabbit notes on BYOA handoff
saif-at-scalekit Aug 14, 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
20 changes: 20 additions & 0 deletions src/content/docs/authenticate/mcp/custom-auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,8 @@ shape: sequence_diagram
https://<SCALEKIT_ENVIRONMENT_URL>/login?login_request_id=<reqid>&state=<state>
```

The login request and its `state` stay valid for approximately 10 minutes. Complete authentication and redirect the user back to Scalekit within that window. If the request expires, the user lands on an `invalid_state` error page and must restart the connection from their MCP client.

Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

2. ## Authenticate the user in your system

Expand Down Expand Up @@ -183,3 +185,21 @@ shape: sequence_diagram


Your MCP server now supports federated authentication with your existing auth system

## Troubleshooting

<details>
<summary>The user lands on an invalid_state error page</summary>

Scalekit redirects the user to a callback with `error=invalid_state` when the login request has expired or the returned `state` does not match the value from step 1. The login request stays valid for approximately 10 minutes.

The error most often appears when a first-time user takes longer than 10 minutes to finish signing up in your system before completing the handshake. Ask the user to start the connection again from their MCP client. The default error page cannot be replaced with a custom page.
Comment thread
saif-at-scalekit marked this conversation as resolved.
Outdated

</details>

<details>
<summary>The handoff request times out with a gateway timeout error</summary>

Create the Scalekit client once at application startup and reuse that single instance across requests. Constructing a new client on every request re-runs the full bootstrap, which opens a fresh connection and fetches a new access token before the request can proceed. That extra work adds latency and can exceed the request deadline, which surfaces as a `deadline_exceeded` gateway timeout on the user-details call. A shared client caches its token and refreshes it internally.
Comment thread
coderabbitai[bot] marked this conversation as resolved.

</details>