Split personal API key docs onto their own page#16880
Open
timgl wants to merge 3 commits into
Open
Conversation
Moves personal API key setup and authentication instructions out of the API overview into a dedicated /docs/api/personal-api-keys page, and rewrites the auth section of the overview to clearly steer readers: OAuth for apps built for other PostHog users, personal API keys for your own scripts and integrations. Generated-By: PostHog Code Task-Id: f66afb43-d72e-43c7-bf33-9120b3cc6bcd
Contributor
Deploy preview
|
Contributor
|
Vale prose linter → found 0 errors, 66 warnings, 12 suggestions in your markdown Full report → Copy the linter results into an LLM to batch-fix issues. Linter being weird? Update the rules!
|
| Line | Severity | Message | Rule |
|---|---|---|---|
| 10:76 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 12:23 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 12:207 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. | PostHogBase.ProductNames |
| 14:47 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 16:114 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 16:232 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 20:9 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 22:117 | warning | 'automations' is a possible misspelling. | PostHogBase.Spelling |
| 23:6 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 23:124 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 27:42 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 27:87 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 31:21 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 39:56 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 41:24 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 45:92 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 111:5 | warning | 'Status code: 503 (Deprecated)' heading should be in sentence case, and product names should be capitalized. | PostHogBase.SentenceCase |
| 146:31 | warning | 'Redoc' is a possible misspelling. | PostHogBase.Spelling |
| 150:63 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 160:71 | suggestion | Address the reader directly. Use 'you' instead of 'the user'. | PostHogDocs.DirectAddress |
| 161:5 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'Feature flags' for the general industry concept. | PostHogBase.ProductNames |
| 162:5 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 162:108 | suggestion | Address the reader directly. Use 'you' instead of 'the user'. | PostHogDocs.DirectAddress |
| 163:5 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 163:108 | suggestion | Address the reader directly. Use 'you' instead of 'the user'. | PostHogDocs.DirectAddress |
contents/docs/api/oauth.mdx — 0 errors, 27 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 2:8 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 7:19 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 7:195 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 9:4 | warning | 'OAuth server endpoints' heading should be in sentence case, and product names should be capitalized. | PostHogBase.SentenceCase |
| 9:4 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 9:17 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 11:11 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 11:17 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 21:4 | warning | 'Client ID Metadata Document (CIMD)' heading should be in sentence case, and product names should be capitalized. | PostHogBase.SentenceCase |
| 23:74 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 25:40 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 28:128 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 52:10 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 56:21 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 68:27 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 72:34 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 77:30 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 79:4 | warning | 'Claiming your OAuth integration' heading should be in sentence case, and product names should be capitalized. | PostHogBase.SentenceCase |
| 79:18 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 81:126 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 81:233 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 83:37 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 83:124 | warning | Use 'PostHog' instead of 'posthog'. | Vale.Terms |
| 87:9 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 98:4 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 99:4 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 100:4 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
contents/docs/api/personal-api-keys.mdx — 0 errors, 3 warnings, 1 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 7:99 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 7:184 | warning | 'automations' is a possible misspelling. | PostHogBase.Spelling |
| 9:81 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 9:116 | suggestion | Address the reader directly. Use 'you can' instead of 'users can'. | PostHogDocs.DirectAddress |
contents/docs/integrate/provisioning.mdx — 0 errors, 14 warnings, 8 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 6:115 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 6:245 | suggestion | Address the reader directly. Use 'you' instead of 'the user'. | PostHogDocs.DirectAddress |
| 6:265 | suggestion | Address the reader directly. Use 'you' instead of 'The user'. | PostHogDocs.DirectAddress |
| 8:140 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 14:15 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 74:144 | warning | 'org's' is a possible misspelling. | PostHogBase.Spelling |
| 100:5 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 106:50 | suggestion | Address the reader directly. Use 'you' instead of 'the user'. | PostHogDocs.DirectAddress |
| 106:145 | suggestion | Address the reader directly. Use 'you' instead of 'the user'. | PostHogDocs.DirectAddress |
| 149:26 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 165:1 | suggestion | Address the reader directly. Use 'you' instead of 'The user'. | PostHogDocs.DirectAddress |
| 179:42 | suggestion | Address the reader directly. Use 'you' instead of 'the user'. | PostHogDocs.DirectAddress |
| 246:44 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 362:28 | warning | Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept. | PostHogBase.ProductNames |
| 363:30 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. | PostHogBase.ProductNames |
| 374:9 | suggestion | Address the reader directly. Use 'you' instead of 'the user'. | PostHogDocs.DirectAddress |
| 376:35 | suggestion | Address the reader directly. Use 'you' instead of 'the user'. | PostHogDocs.DirectAddress |
| 379:32 | warning | Use 'PostHog' instead of 'posthog'. | Vale.Terms |
| 386:14 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 398:38 | warning | 'OAuth' is a possible misspelling. | PostHogBase.Spelling |
| 423:18 | warning | Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. | PostHogBase.ProductNames |
| 435:20 | warning | Use 'PostHog' instead of 'posthog'. | Vale.Terms |
The deploy preview build fails because the previous build's gatsby-plugin-mdx scope files (cached via actions/cache) still reference this snippet. Restoring it keeps the cache resolvable; the snippet is no longer imported anywhere in this PR. Generated-By: PostHog Code Task-Id: f66afb43-d72e-43c7-bf33-9120b3cc6bcd
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
1 participant
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.
Summary
/docs/api/personal-api-keyswith the obtain + authenticate instructions, plus a callout at the top steering app-builders to OAuth.personal-api-keysandoauth, with a blockquote making the choice obvious: building an app for others → OAuth; using PostHog from your own scripts/project → personal API key.src/navs/index.js)./docs/api#private-endpoint-authenticationlinks inoauth.mdxandintegrate/provisioning.mdxto point at the new page. Removed the now-orphanedinstall-api.mdxsnippet (theobtain-personal-api-key.mdxsnippet it imported is still used by the new page).Test plan
pnpm startand confirm/docs/api/personal-api-keysrenders with the obtain + authenticate sections and the OAuth callout./docs/api"Authentication" section shows the two links and the bolded recommendation./docs/api/oauthand/docs/integrate/provisioningnow resolve to/docs/api/personal-api-keys.