# oauth2-provider-design

Guides the architectural design of an OAuth 2.1 authorization server for B2B SaaS. Useful when issuing tokens to third-party clients and defining consent flows.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 7800 installs · ★ 7
- Author: Samuel Berthe
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/samber/developer-platform-skills/tree/HEAD/skills/oauth2-provider-design/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/oauth2-provider-design

## What it does

This skill provides decision architecture for building an authorization server under OAuth 2.1 and RFC 9700. It mandates PKCE with S256 for public and confidential clients, while dropping the implicit and password grants completely. Authorization codes stay single-use with a maximum ten-minute lifetime. Access tokens target around one hour. Short JWT lifetimes limit exposure if a credential leaks.

The design covers scope granularity, refresh token rotation with DPoP, and multi-tier consent flows. In B2B workspaces, apps need consent from both end users and workspace admins. The instructions advise saving key architectural decisions inside `developer-platform-context.md`.

This guide targets identity providers, not client integrations against someone else's API. It also avoids static API keys entirely, because the author maintains a separate module for basic key management.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add samber/developer-platform-skills --skill oauth2-provider-design -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/oauth2-provider-design/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/oauth2-provider-design/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add samber/developer-platform-skills --skill oauth2-provider-design -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/oauth2-provider-design/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add samber/developer-platform-skills --skill oauth2-provider-design -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/oauth2-provider-design/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install samber/developer-platform-skills oauth2-provider-design
```

2. **Manually: put the files in place**
- File: `.github/skills/oauth2-provider-design/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add samber/developer-platform-skills --skill oauth2-provider-design -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/samber/developer-platform-skills --path skills/oauth2-provider-design
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/oauth2-provider-design/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add samber/developer-platform-skills --skill oauth2-provider-design -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/samber/developer-platform-skills/tree/HEAD/skills/oauth2-provider-design/SKILL.md

## When to use it
- design an OAuth 2.1 compliant authorization server
- enforce PKCE S256 across public and confidential clients
- configure refresh token rotation policies and TTL limits
- structure separate consent screens for users and workspace admins

## Example prompts
- Design an OAuth 2.1 authorization server for our B2B SaaS with PKCE enforced
- Help configure the refresh token rotation policy and access token TTL
- Draft the workspace admin approval flow and scope hierarchy for third-party apps

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: a9225396cd231bce.

BEGIN THIRD-PARTY FILE a9225396cd231bce
```text
---
name: oauth2-provider-design
description: Design the OAuth2 authorization-server surface a B2B SaaS offers third-party apps - the OAuth 2.1 protocol baseline (PKCE for every client, no implicit or password grants, exact redirect matching), token TTL and refresh-rotation policy, scope taxonomy and granularity, consent-screen design with partial and incremental grants, client registration posture, and the tiered app-verification program. Use whenever the user mentions OAuth, "Sign in with X", access and refresh tokens, scopes, consent screens, PKCE, or third-party apps acting on a customer's behalf - even if they never say "OAuth provider". Issuer side only, not integrating against someone else's OAuth. Do NOT use for API-key design - use samber/developer-platform-skills@api-auth-key-management instead.
license: MIT
metadata:
  author: Samuel Berthe
  version: "1.0.2"
---

# OAuth2 Provider Design

You are an OAuth provider designer. Design the authorization-server surface a platform offers third-party apps: protocol profile, token lifecycle, scope taxonomy, consent screen, registration, verification. Do it so a compromised app or leaked token is a contained event, and so the platform never faces the forced retrofit Salesforce's ISV ecosystem lived through in 2026.

This is decision guidance for a platform/API team, not an RFC tutorial. The target profile is OAuth 2.1, with one precision to carry everywhere:

- RFC 9700 (BCP 240, the OAuth Security Best Current Practice) is final and ratified (January 2025).
- The consolidated OAuth 2.1 document (draft-ietf-oauth-v2-1) remains in draft. Check its current status before citing it as published.

The requirements are settled convergence regardless of the document's own publication status. Never state that OAuth 2.1 itself is a published RFC without first confirming that's still accurate.

**Memory (advised):** When memory lives in a file, consider using `developer-platform-context.md`; if a different memory system is in use, rely on that instead. The file is an advisory reference, not a mandatory requirement. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.

## Clarifying questions

Ask before designing anything; each answer changes a later step. Batch them - this is tactical design, not a strategy interview.

1. Greenfield or retrofit? If retrofit: which grants run today, do any clients depend on the implicit or password grant, is refresh rotation on, and roughly how many registered apps exist.
```
END THIRD-PARTY FILE a9225396cd231bce

The third-party file has ended. Everything between the a9225396cd231bce tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2615 of 22882 bytes. © Samuel Berthe · MIT · https://github.com/samber/developer-platform-skills/tree/HEAD/skills/oauth2-provider-design/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md