Skip to content

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

  1. 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.
  2. Send people to jsonresume.org

    Link to the authorization page with the scopes you need, a random state and, for OpenID Connect, a nonce. 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=$NONCE
  3. Swap the code for tokens

    They come back to your redirect URI with code and your state. From your server, exchange the code within 10 minutes. With the openid scope you also get an id_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/callback
  4. Read 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

Scopes, space-separated in scope=
ScopeLets your app
openidAn OpenID Connect ID token with the tokens: a JWT (RS256) naming them, with the claims your other scopes allow.
profileTheir username, name, photo and page, from /api/oauth/userinfo. What you get when you ask for nothing.
emailTheir email address, and whether it is verified.
resume:readTheir resume as JSON Resume, from GET /api/oauth/resume.
resume:writeReplace their resume with PUT /api/oauth/resume. Saved to their gist when their page reads from it, and checked against the schema.
mcpEverything, through the MCP server. For agents, not HR tools.

Reference

Endpoints

Endpoints
Authorizationhttps://jsonresume.org/oauth/authorize
TokenPOST https://jsonresume.org/api/oauth/token
User infoGET https://jsonresume.org/api/oauth/userinfo
ResumeGET, PUT https://jsonresume.org/api/oauth/resume
RevocationPOST https://jsonresume.org/api/oauth/revoke
Signing keys (JWKS)GET https://jsonresume.org/api/oauth/jwks
OpenID configurationhttps://jsonresume.org/.well-known/openid-configuration
Metadata (RFC 8414)https://jsonresume.org/.well-known/oauth-authorization-server

Details

Good to know

  • Use sub as the user’s ID: usernames can change.
  • Any OpenID Connect library works from the issuer https://jsonresume.org alone: it reads the endpoints and keys from /.well-known/openid-configuration. ID tokens are RS256, last an hour, and carry your nonce.
  • 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 gets mcp, which is everything.
  • Redirect URIs must be https, or http on 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 https URL for your app under Settings → Your OAuth apps (or MCP set_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. Check JSONResume-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) and insufficient_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.

Works with JSON Resume
Works with JSON Resume, for dark backgrounds
<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>

Building for agents instead?