Add JWT authentication flow documentation #1752
Conversation
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
- Create new MCP server documentation page under Ask Fern features - Add comprehensive API reference for get-jwt and search/v2/key endpoints - Include OpenAPI 3.1 specification with downloadable YAML file - Update navigation to include MCP server page - Replace JWT auth flow in api-get-started.mdx with link to MCP docs Co-Authored-By: [email protected] <[email protected]>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| - **Automated testing**: Programmatically verify documentation content and search functionality | ||
| - **Custom integrations**: Build tools that need to access protected documentation content | ||
|
|
||
| ## API reference |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[FernStyles.Reject] Use 'API Reference' instead of 'API reference'.
|
|
||
| | Status | Description | | ||
| |--------|-------------| | ||
| | 400 | JWT generation is not accessible in local preview mode | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'isn't' instead of 'is not'.
| | Status | Description | | ||
| |--------|-------------| | ||
| | 400 | JWT generation is not accessible in local preview mode | | ||
| | 400 | JWT generation is not supported in self-hosted environments | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'isn't' instead of 'is not'.
| |--------|-------------| | ||
| | 400 | JWT generation is not accessible in local preview mode | | ||
| | 400 | JWT generation is not supported in self-hosted environments | | ||
| | 400 | SSO/WorkOS authentication is not supported by this endpoint | |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'SSO' has no definition.
| |--------|-------------| | ||
| | 400 | JWT generation is not accessible in local preview mode | | ||
| | 400 | JWT generation is not supported in self-hosted environments | | ||
| | 400 | SSO/WorkOS authentication is not supported by this endpoint | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'isn't' instead of 'is not'.
| | 400 | SSO/WorkOS authentication is not supported by this endpoint | | ||
| | 401 | Missing `FERN_API_KEY` header | | ||
| | 401 | Invalid API key | | ||
| | 403 | API key does not belong to the organization that owns this domain | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'doesn't' instead of 'does not'.
|
|
||
| | Status | Description | | ||
| |--------|-------------| | ||
| | 400 | Search key is not accessible in local preview mode | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'isn't' instead of 'is not'.
| | Status | Description | | ||
| |--------|-------------| | ||
| | 400 | Search key is not accessible in local preview mode | | ||
| | 400 | Search is not supported for preview URLs (unless explicitly enabled) | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'isn't' instead of 'is not'.
| | 400 | Search key is not accessible in local preview mode | | ||
| | 400 | Search is not supported for preview URLs (unless explicitly enabled) | | ||
| | 401 | Invalid API key | | ||
| | 403 | API key does not belong to the organization that owns this domain | |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'doesn't' instead of 'does not'.
- Remove empty fern/apis/fern-docs-mcp directory causing CI failure - Change 'API reference' to 'API Reference' per FernStyles.Reject rule - Use contractions (isn't, doesn't) per Microsoft.Contractions - Define SSO (Single sign-on) on first use per FernStyles.Acronyms - Fix broken link in api-get-started.mdx to use correct path - Remove download link to openapi.yaml (file not hosted) Co-Authored-By: [email protected] <[email protected]>
| |--------|-------------| | ||
| | 400 | JWT generation isn't accessible in local preview mode | | ||
| | 400 | JWT generation isn't supported in self-hosted environments | | ||
| | 400 | Single sign-on (SSO)/WorkOS authentication isn't supported by this endpoint | |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'SSO' has no definition.
- Create fern/apis/fern-docs-mcp/openapi.json with OpenAPI 3.1.0 spec - Add generators.yml to properly configure the API definition - Update MCP server documentation to reference the API spec location - Includes both get-jwt and search/v2/key endpoints with full specifications Co-Authored-By: [email protected] <[email protected]>
Add MCP server API reference documentation
Summary
Created comprehensive API reference documentation for two Fern Docs endpoints that enable MCP (Model Context Protocol) agents to authenticate and search documentation:
The documentation includes:
fern/apis/fern-docs-mcp/with OpenAPI 3.1.0 specDocumentation approach: Created by examining actual route implementations in
fern-platform/packages/fern-docs/bundle/src/app/[host]/[domain]/api/fern-docs/to ensure accuracy of headers, authentication flows, and error responses.Review & Testing Checklist for Human
Test the complete authentication flow end-to-end: Run the documented curl commands with a real Fern API key against an actual protected docs site. The most critical thing to verify is the header syntax - specifically whether
FERN_API_KEY:${VAR}(with colon directly after header name) is correct or if it should beFERN_API_KEY: ${VAR}(with space after colon). The code uses these as custom header names, but the curl syntax may differ.Verify the CLI command: The docs reference
fern tokenfor generating API keys. Confirm this is the correct command (notfern generate token) by checking the actual CLI behavior or canonical CLI documentation.Validate the OpenAPI specification: The
fern/apis/fern-docs-mcp/openapi.jsonfile was hand-written based on code inspection. Test it with an OpenAPI validator and consider generating a client from it to verify the schema accuracy, especially for:rolesfield in responses (conditionally present based on auth method)Test environment restrictions: Verify the documented behaviors for local preview (400 errors), self-hosted environments (400 for JWT, mock credentials for search), and preview URLs actually match the implementation. These were inferred from code but not tested.
Check if the OpenAPI spec should be surfaced in navigation: The API definition exists at
fern/apis/fern-docs-mcp/but isn't wired into the Ask Fern product navigation as a separate API Reference section. Determine if this is intentional or if anapi:block should be added toask-fern.ymlto make it discoverable in the sidebar.Notes
docs.example.comand plant-themed examples (botanist, seedling, aloe-bot-42) per style guidelines