Repository navigation
docs: add authentication API specs (OpenAPI, ADR) with visual API map - #479
Open
subhashree-sahu31 wants to merge 1 commit into
Conversation
kramakrushna
changed the title
…I map
- Add OpenAPI 3.0.3 contracts for auth-owned APIs:
docs/openapi/{components,authn-openapi,third-party-auth-openapi,oauth2-openapi}.yaml
- Add ADR-style specs for registration/login, third-party auth, and
OAuth2 bridge flows under docs/specs/{registration-login,
third-party-auth,oauth2-bridge}/spec.rst
- Add consolidated Confluence-ready SDD document
(docs/specs/SDD-Authentication-APIs.md) covering:
- Endpoint-by-endpoint request/response/error detail for all
~38 endpoints across the three domains
- Full API schema reference (request/response/error models)
- Step-by-step integration guide with curl examples and a
best-practices checklist
- Color-coded, Swagger-style visual API map (Mermaid flowcharts
and HTTP-method badges) for registration/login, TPA pipeline,
and OAuth2 bridge flows
subhashree-sahu31
force-pushed
the
AUT-314-create-sdd-specifications-api-schemas-for-edx-platform-auth-flows
branch
from
October 5, 2026 15:15
540dd2f to
f17ca5c
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Documented request formats, response schemas, and authorization requirements materially contradict the implementation and would mislead integrations.
34 open findings
And 14 more that still need to be addressed.
What changed in this PR
Adds documentation for existing authentication APIs to support client integration and developer onboarding. No runtime code changes are included.
Changes:
- Adds OpenAPI contracts and shared schemas for core authentication, third-party authentication, and OAuth2.
- Adds companion specifications describing flows and security requirements.
- Adds documentation indexes and validation instructions.
| File | Description |
|---|---|
docs/specs/third-party-auth/spec.rst |
Federated authentication flows and account linking. |
docs/specs/registration-login/spec.rst |
Registration, login, and password-reset flows. |
docs/specs/README.rst |
Specification index and conventions. |
docs/specs/oauth2-bridge/spec.rst |
OAuth2 grants, token lifecycle, and JWT guidance. |
docs/openapi/third-party-auth-openapi.yaml |
Federated authentication and provider API contracts. |
docs/openapi/README.md |
Viewing, validation, and scope guidance. |
docs/openapi/oauth2-openapi.yaml |
OAuth2 issuance, revocation, and exchange contracts. |
docs/openapi/components.yaml |
Shared schemas and security definitions. |
docs/openapi/authn-openapi.yaml |
Core authentication endpoint contracts. |
🧠 Review effort: Balanced
Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.
Comment on lines
+111
to
+112
| allOf: | ||
| - $ref: '#/components/schemas/FieldErrors' |
Comment on lines
+58
to
+62
| Identical to `POST /api/user/v2/account/registration/`, except the | ||
| client must resubmit the email address a second time via a | ||
| `confirm_email` field, and some duplicate-account error codes use | ||
| the legacy `duplicate` value instead of the more specific | ||
| `duplicate-email`/`duplicate-username` codes. |
Comment on lines
+64
to
+65
| security: | ||
| - CsrfToken: [] |
Comment on lines
+147
to
+161
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/RegistrationRequest' | ||
| examples: | ||
| minimal: | ||
| value: | ||
| username: janedoe | ||
| email: jane@example.com | ||
| password: correct-horse-battery-staple | ||
| name: Jane Doe | ||
| honor_code: true | ||
| terms_of_service: true | ||
| application/x-www-form-urlencoded: | ||
| schema: | ||
| $ref: '#/components/schemas/RegistrationRequest' |
| schema: | ||
| $ref: 'components.yaml#/components/schemas/LoginErrorResponse' | ||
| '403': | ||
| description: Forbidden - account locked out, rate limited, or TPA-only account. |
Comment on lines
+502
to
+504
| security: | ||
| - JwtAuth: [] | ||
| - OAuth2: [tpa:read] |
Comment on lines
+88
to
+90
| passed. Restricted-application tokens are additionally issued with | ||
| ``expires_in <= 0`` (immediately expired) so they carry an audit trail | ||
| without granting live API access. |
Comment on lines
+192
to
+195
| * JWT signature verification MUST use the key identified by the token's | ||
| ``kid`` header looked up via ``/auth/jwks.json``; relying parties MUST | ||
| reject tokens signed with an unknown ``kid`` rather than falling back to | ||
| a default key. |
| (``partial_pipeline`` present in session), the pending social-auth | ||
| association is completed as part of this request. | ||
| 2. **Validation failed** (``400``) - one or more fields failed validation; | ||
| response includes ``field_errors`` keyed by field name. No account is |
Comment on lines
+157
to
+159
| * Successful confirmation always leaves the account ``is_active=True``, | ||
| even if it was inactive before (this doubles as an implicit activation | ||
| path). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR adds complete API specifications and design documentation for edX Platform's authentication flows: core registration/login, third-party authentication (TPA), and the OAuth2 bridge.
It introduces:
docs/openapi/) — machine-readable schemas for all auth-team-owned endpoints:authn-openapi.yaml— registration, login, logout, password reset/activation, MFE context, JWKSthird-party-auth-openapi.yaml— TPA pipeline endpoints (SAML/OAuth provider login, association management)oauth2-openapi.yaml— OAuth2 token issuance, refresh, revocation, and JWT claim schemascomponents.yaml— shared schemas/security definitions used across the abovedocs/specs/{registration-login,third-party-auth,oauth2-bridge}/spec.rst) — narrative design docs per OEP-19, covering context, decisions, and rationale for each auth flow.docs/specs/SDD-Authentication-APIs.md) — a single, Confluence-ready Markdown document that ties the above together, including:curlexamples and a best-practices checklistNo functional/runtime code is changed — this is a documentation-only PR that formalizes existing authentication API behavior.
User roles impacted: Developer (primarily) — this documents existing behavior to aid integration and onboarding. No impact on Learner, Course Author, or Operator roles.
Supporting information
Testing instructions
This is a documentation-only change; no application behavior is affected. To verify:
3.Preview docs/specs/SDD-Authentication-APIs.md in VS Code/GitHub to confirm Mermaid diagrams and tables render as expected.
Other information
Documentation-only change; no dependency on other in-flight changes.
No database migrations, no deprecations introduced.
Mermaid diagrams in the SDD Markdown file require a Mermaid-capable renderer (native in GitHub/VS Code; Confluence requires the "Mermaid Diagrams for Confluence" macro or similar) — this caveat is noted directly in the document.