Published 2026-09-22 · Tested 2026-09-22

WorkOS

A-

WorkOS received 10 PASS votes and passed 5 of five agent surface checks. The clearest finding came from the find the exact limits task.

Panel: GPT 5.6 Sol, Opus 5, DeepSeek v4F Battery: v1 Read as markdown (opens in a new tab)

Three AI models, GPT 5.6 Sol, Claude Opus 5, and DeepSeek v4 Flash, each read WorkOS’s public documentation independently and attempted five first-hour developer jobs: add AuthKit sign-in to a Next.js app, find the exact limits, recover from a 429, verify a webhook, use the Node SDK.

No accounts, API calls, or code execution were used. Every verdict came from public pages and every published quotation passed a live verification check.

Freshness

How rechecks work
Category
Identity & auth
Tested
Quotes verified
Surface rechecked
Not yet rechecked
WorkOS Custom Next.js · published
A-

92.5% · 74/80 · AI Agent Readiness Score · reading 30 pts · surface 50 pts

llms.txt PASS
llms-full.txt PASS
markdown mirror PASS
MCP server PASS
docs AI PASS
Task GPT 5.6 SolOpus 5DeepSeek v4F Consensus
Add AuthKit sign-in to a Next.js app PARTIALPASSPASS PASS
Find the exact limits FAILPARTIALPARTIAL PARTIAL
Recover from a 429 PASSPASSPASS PASS
Verify a webhook PARTIALPASSPASS PASS
Use the Node SDK PASSPASSPASS PASS

docs platform: Custom Next.js (unscored) · verified 2026-09-22

What to fix first

This fix could add up to 4 points to the AI Agent Readiness Score. The list ranks each fix by the points it would add. How the ranking works

  1. 1
    +4 points Find the exact limits PARTIAL

    Found: The rate limits page gives exact general and AuthKit numbers but describes default email sending only as adaptive, with no number an agent can plan against.

    Fix: Publish the default email provider's starting sending limit and how it scales on the rate limits page, alongside the general and AuthKit numbers.

    Evidence: workos.com/docs/reference/rate-limits (opens in a new tab)

What the docs get right

  • Recover from a 429: 3 PASS votes. The rate-limit page gives both the server retry signal and a fallback when that header is absent.
  • Use the Node SDK: 3 PASS votes. The SDK page supplies installation, and the Organization reference maps getOrganization to GET /organizations/:id.
  • 5 of 5 agent surface checks. Present: llms.txt, llms-full.txt, markdown mirrors, an MCP server, docs AI.

Add AuthKit sign-in to a Next.js app

PASS

PASS consensus from 2 PASS, 1 PARTIAL.

The guide reaches a signed-in user, but it alternates between NEXT_PUBLIC_WORKOS_REDIRECT_URI and WORKOS_REDIRECT_URI for the callback setting. One numbered guide runs from API key and client ID through install, redirect URI, proxy, callback route, and withAuth() returning the signed-in user, and workos.com/auth.md lets an agent provision a working API key with no account at all. The authkit-nextjs SDK page walks through installing packages, setting env vars (including WORKOS_API_KEY from the dashboard), creating a callback route with handleAuth(), a sign-in route with getSignInUrl(), middleware with authkitMiddleware(), and retrieving the user with withAuth() all in one coherent guide.

Find the exact limits

PARTIAL

PARTIAL consensus from 2 PARTIAL, 1 FAIL.

The page gives exact general and AuthKit request limits but no numeric limit for the default email provider. General (6,000 requests per 60 seconds per API key) and AuthKit (1,000 reads and 500 writes per 10 seconds per environment) are exact and scoped, but the default email provider's sending limits are stated only qualitatively, with no number an agent can plan against. General endpoint limits (6,000 req/60s per API key) and AuthKit limits (1,000 reads/10s, 500 writes/10s per environment) are exact and clearly scoped. However, default email sending limits are deliberately non-exact, described as adaptive, scaling with sending history, and not quantified. An agent cannot find a precise number for email sending limits.

Recover from a 429

PASS

PASS consensus from 3 PASS.

The rate-limit page gives both the server retry signal and a fallback when that header is absent. The 429 entry in the error table links straight to Rate limits, which gives the retry signal, the backoff rule, and the per-API-key counting scope, and the Node SDK page documents matching automatic retries with idempotency keys; no example 429 body or rate-limit headers beyond Retry-After are documented. The rate limits page gives the retry signal (Retry-After header) and fallback strategy (exponential backoff with random delay). The Node SDK page adds that SDKs auto-retry with 3 attempts, exponential backoff, and jitter, honoring Retry-After up to 60 seconds. The errors page confirms 429 maps to 'Too Many Requests' and directs to the rate limits page.

Verify a webhook

PASS

PASS consensus from 2 PASS, 1 PARTIAL.

The guide covers registration, receipt, testing, and verification, but its JavaScript example parses JSON before a raw-body check. The guide covers endpoint setup, registration, the WorkOS-Signature header and its lowercase normalization, SDK verification, manual HMAC SHA256 verification, tolerance, retry behaviour, and an IP allowlist, and the API reference links back to it for implementation detail. The webhooks guide covers the full lifecycle: creating an HTTPS endpoint, registering it in the dashboard, responding 200 OK, and validating signatures via the SDK (workos.webhooks.constructEvent) or manually (HMAC-SHA256 over 'issued_timestamp.body' using the webhook secret). The API reference provides webhook endpoint CRUD and cross-links to the guide. Both pages agree on the protocol.

Use the Node SDK

PASS

PASS consensus from 3 PASS.

The SDK page supplies installation, and the Organization reference maps getOrganization to GET /organizations/:id. The SDK page gives install, new WorkOS('sk_1234'), retry and timeout behaviour, and PKCE examples, and most API reference operations carry a matching JavaScript tab, though the webhook endpoint operations offer curl plus seven other languages and no Node example. The official Node SDK is documented with package name (@workos-inc/node), installation command (npm install), requirements (Node 22.11+), and a minimal working example (import, construct with API key, call methods). The API Reference client-libraries page shows the same install command and links to Node usage examples, agreeing on the SDK form.

The receipt

These limits scale with an environment's sending history and are tuned to respond to abuse patterns such as spam and phishing.

General (6,000 requests per 60 seconds per API key) and AuthKit (1,000 reads and 500 writes per 10 seconds per environment) are exact and scoped, but the default email provider's sending limits are stated only qualitatively, with no number an agent can plan against.

Agent surface notes

Initialize returned HTTP 401 with a Bearer OAuth challenge naming resource metadata at mcp.workos.com/.well-known/oauth-protected-resource/mcp.

The docs home links Ask WorkOS to ask.workos.com, which opens a public assistant headed Ask WorkOS with a question box and no sign-in requirement.

Show the score

AI Agent Readiness Score 92.5%, grade A-

Paste this into a readme:

[![AI Agent Readiness Score 92.5%](https://docsforagents.com/badge/workos.svg)](https://docsforagents.com/reports/workos-docs-ai-agent-readiness/)

Method note

This is a reading test of public documentation, not an execution test. No accounts were created and no API calls were run. The AI Agent Readiness Score counts fifteen reading votes at PASS 2, PARTIAL 1, and FAIL 0, for 30 possible points. Five agent surface checks add 10 points each. The total is 80. Consensus chips show each row majority and do not affect scoring. The panel split on 3 of five tasks. Quotes shown here were re-fetched and confirmed verbatim on 2026-09-22.

Read the full methodology

Put another docs site through the battery.

Nominate a docs site