Developers
Sign in with JSON Resume
Let people bring their resume to your HR tool, job board or applicant tracker. They sign in with jsonresume.org and choose what you may see; you get their resume.json, kept up to date by them, with no forms to fill in again.
// auth.ts: Auth.js (NextAuth) with JSON Resume as a provider
providers: [
{
id: 'jsonresume',
name: 'JSON Resume',
type: 'oidc',
issuer: 'https://jsonresume.org',
authorization: {
params: { scope: 'openid profile email resume:read' },
},
clientId: process.env.JSONRESUME_CLIENT_ID,
clientSecret: process.env.JSONRESUME_CLIENT_SECRET,
profile: (p) => ({
id: p.sub,
name: p.name ?? p.preferred_username,
email: p.email,
image: p.picture,
}),
},
],OAuth 2.1
How it works
Register your app
Under Settings → Your OAuth apps, give its name and the URLs people come back to. You get a client ID and a secret, shown once. Keep the secret on your server.Send people to jsonresume.org
Link to the authorization page with the scopes you need, a randomstateand, for OpenID Connect, anonce. They sign in (or sign up), see exactly what you asked for, and choose Allow.https://jsonresume.org/oauth/authorize?response_type=code &client_id=$CLIENT_ID &redirect_uri=https%3A%2F%2Facme.example%2Fauth%2Fjsonresume%2Fcallback &scope=openid%20profile%20email%20resume:read &state=$STATE &nonce=$NONCESwap the code for tokens
They come back to your redirect URI withcodeand yourstate. From your server, exchange the code within 10 minutes. With theopenidscope you also get anid_token: who they are, signed. Access tokens last an hour; refresh tokens 90 days, and each is used once.curl https://jsonresume.org/api/oauth/token -u "$CLIENT_ID:$CLIENT_SECRET" \ -d grant_type=authorization_code \ -d code=$CODE \ -d redirect_uri=https://acme.example/auth/jsonresume/callbackRead their resume
Send the access token as a Bearer token. Who they are is at/api/oauth/userinfo; their resume, as JSON Resume, at/api/oauth/resume.curl https://jsonresume.org/api/oauth/resume -H "Authorization: Bearer $ACCESS_TOKEN"
Ask for what you need
Scopes
| Scope | Lets your app |
|---|---|
openid | An OpenID Connect ID token with the tokens: a JWT (RS256) naming them, with the claims your other scopes allow. |
profile | Their username, name, photo and page, from /api/oauth/userinfo. What you get when you ask for nothing. |
email | Their email address, and whether it is verified. |
resume:read | Their resume as JSON Resume, from GET /api/oauth/resume. |
resume:write | Replace their resume with PUT /api/oauth/resume. Saved to their gist when their page reads from it, and checked against the schema. |
mcp | Everything, through the MCP server. For agents, not HR tools. |
Reference
Endpoints
| Authorization | https://jsonresume.org/oauth/authorize |
| Token | POST https://jsonresume.org/api/oauth/token |
| User info | GET https://jsonresume.org/api/oauth/userinfo |
| Resume | GET, PUT https://jsonresume.org/api/oauth/resume |
| Revocation | POST https://jsonresume.org/api/oauth/revoke |
| Signing keys (JWKS) | GET https://jsonresume.org/api/oauth/jwks |
| OpenID configuration | https://jsonresume.org/.well-known/openid-configuration |
| Metadata (RFC 8414) | https://jsonresume.org/.well-known/oauth-authorization-server |
Details
Good to know
- Use
subas the user’s ID: usernames can change. - Any OpenID Connect library works from the issuer
https://jsonresume.orgalone: it reads the endpoints and keys from/.well-known/openid-configuration. ID tokens are RS256, last an hour, and carry yournonce. - PKCE (S256) is optional for apps with a secret and required for apps without one. Browser and mobile apps without a server can register themselves (RFC 7591,
POST /api/oauth/register) and must use PKCE. - Always send
scope. A self-registered app that asks for nothing getsmcp, which is everything. - Redirect URIs must be
https, orhttpon loopback only, with no#fragment. An app scheme (myapp://callback) also works. - People see every app they’ve connected under Settings → Connected apps, and can disconnect it there. Revoke a token yourself when someone disconnects on your side.
- Webhooks: set an
httpsURL for your app under Settings → Your OAuth apps (or MCPset_app_webhook). When someone who granted a resume scope changes their resume, we POST{"id", "type": "resume.updated", "created_at", "user": {"sub", "username"}}, retried for a day until you answer 2xx. CheckJSONResume-Signature: t=…,v1=…(the hex HMAC-SHA256 of<t>.<body>with your signing secret), then read the resume with your token. - Errors follow RFC 6749 and 6750:
invalid_grant,invalid_client,invalid_token(401) andinsufficient_scope(403).
In the wild
Built with JSON Resume
Independent apps built on Sign in with JSON Resume. Built one? Add it to the projects directory in a pull request and it can be listed here.
Badge
Works with JSON Resume
Apps that sign people in with JSON Resume may show this badge, linking to jsonresume.org. Use the dark one on dark backgrounds. It says your app works with JSON Resume, not that JSON Resume made or endorses it.
<a href="https://jsonresume.org">
<img src="https://jsonresume.org/badges/works-with-jsonresume.svg" alt="Works with JSON Resume" width="218" height="36">
</a>