Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Machine Token Docs #1725

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

feat: Machine Token Docs #1725

wants to merge 9 commits into from

Conversation

Ben2W
Copy link

@Ben2W Ben2W commented Nov 20, 2024

Note to reviewer:
There is not too much content, however I did restructure the docs which is why there are 61 files changed
Let me know if you want me to go about this PR in a different way (ie splitting the PR up or not changing the links around or maybe only change the manifest.json to make it appear the structure was changed, without affecting the links?)

Currently all customer-facing tokens are session tokens. We are adding machine tokens which is another customer-facing token. This PR adds documentation on:

  • Understanding machine tokens
  • Creating machine tokens
  • Using machine tokens to authenticate requests
  • authenticating requests with machine tokens.

Additionally because now, all backend requests may no longer have a user + session associated with them, I modified the structure of some of the docs pages, and slightly edited existing pages to help fit the concept of "machine authentication". Read below to see what I changed.

Created the following machine request pages:

/docs/machine-requests/overview
/docs/machine-requests/machine-tokens
/docs/machine-requests/manual-jwt

Moved most of the "Backend Requests" pages to "Session Requests"

Calling this section "backend request" is confusing because machine requests are also backend requests.

This caused most of the "files changed" in the PR because a lot of links were changed from @NWylynko's script.

Old Path New Path
/docs/backend-requests/overview /docs/session-requests/overview
/docs/backend-requests/making/same-origin /docs/session-requests/making/same-origin
/docs/backend-requests/making/cross-origin /docs/session-requests/making/cross-origin
/docs/backend-requests/making/custom-session-token /docs/session-requests/making/custom-session-token
/docs/backend-requests/making/jwt-templates /docs/session-requests/making/jwt-templates
/docs/backend-requests/handling/go /docs/backend-requests/handling/go
/docs/backend-requests/handling/ruby-rails /docs/backend-requests/handling/ruby-rails
/docs/backend-requests/handling/manual-jwt /docs/backend-requests/handling/manual-jwt
/docs/backend-requests/resources/session-tokens /docs/backend-requests/session-tokens

Some pages that were in "Backend Requests" didn't fit under "Session Requests," so they were moved to their own section:

Old Path New Path
/docs/backend-requests/versioning/overview /docs/versioning/overview
/docs/backend-requests/versioning/available-versions /docs/versioning/available-versions
/docs/backend-requests/resources/rate-limits /docs/resources/rate-limits

Modified the following pages to add the concept of machine authentication:

Old Docs Page New Docs Page
https://clerk.com/docs/references/nextjs/auth https://clerk.com/docs/pr/1725/references/nextjs/auth
https://clerk.com/docs/references/backend/authenticate-request https://clerk.com/docs/pr/1725/references/backend/authenticate-request
https://clerk.com/docs/references/backend/types/auth-object https://clerk.com/docs/pr/1725/references/backend/types/auth-object

Slack thread:
https://clerkinc.slack.com/archives/C01QFRQNHSN/p1738141182851989

Checklist

  • [ x ] I have clicked on "Files changed" and performed a thorough self-review
  • [ x ] I have added the "deploy-preview" label and added the preview link(s) to this PR description
  • All existing checks pass

Copy link

Hey, here’s your docs preview: https://clerk.com/docs/pr/1725

@Ben2W Ben2W force-pushed the ben/machine-tokens branch from f25d216 to d6aa27f Compare November 21, 2024 00:40
@Ben2W Ben2W force-pushed the ben/machine-tokens branch from ff5ca46 to 155ff57 Compare January 28, 2025 20:21
running prettier

removing redundant ids

a "valid" id was in fact - not valid

removing unneccessary "s"

reverting

adding pages back in different folder

some minor changes

machine_id has a 255 character limit

Some Colin Notes
Copy link

Hey, here’s your docs preview: https://clerk.com/docs/pr/1725

@Ben2W Ben2W marked this pull request as ready for review January 29, 2025 08:50
@Ben2W Ben2W requested a review from a team as a code owner January 29, 2025 08:51
@Ben2W Ben2W marked this pull request as draft January 29, 2025 08:55
@Ben2W Ben2W marked this pull request as ready for review January 29, 2025 08:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant