feat: Machine Token Docs #1725

Ben2W · 2024-11-20T03:36:06Z

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?)

Clerk redirects PR: https://github.com/clerk/clerk/pull/964

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

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

github-actions · 2024-11-20T03:42:36Z

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

github-actions · 2025-01-28T20:24:05Z

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

docs/machine-requests/overview.mdx

jakobevangelista · 2025-02-03T22:16:51Z

docs/machine-requests/overview.mdx

+
+#### Examples
+
+  <Tabs items={['Next.js Middleware', 'Next.js API Route']}>


feels weird to me that the authenticateRequest() example is in a whole different tab, but it makes sense because authenticateRequest() is it's own thing, i might be too in the weeds / looking too deep into it

Yea for me I think these examples are how to use machine to machine in backend frameworks.

However, since we only have Next.js, it feels weird that these are our only examples.

docs/machine-requests/manual-jwt.mdx

docs/machine-requests/overview.mdx

docs/machine-requests/manual-jwt.mdx

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

editing session requests slightly

improving authenticateRequest docs page updating auth object type editing nextjs auth docs page Removing unnecessary preface

Co-authored-by: Jakob Evangelista <[email protected]>

Co-authored-by: Bryce Kalow <[email protected]>

Ben2W · 2025-02-07T08:10:17Z

@brkalow And @jakobevangelista

I addressed all of the comments (thanks for reviewing it).

Few things:

After rebasing the auth() reference doc was changed by someone else, I also found a small issue with authenticateRequest() so I pushed this commit: d7da65d
I changed the manifest.json to put "Backend Requests" at the same level as "Configuration.

jakobevangelista · 2025-02-07T16:18:04Z

lgtm, prolly should ask alexis and/or nick for an extra opinions about the backend section change

NWylynko · 2025-02-07T17:52:09Z

docs/machine-requests/overview.mdx

+
+#### Examples
+
+<Tabs items={['Next.js API Route', 'Next.js Middleware']}>


Are you suggesting these two examples get used in unison? To me I feel that the best option is to have an explicit ignore in the middleware, and then do the check in the route. But this looks to suggest doing one or the other?

NWylynko · 2025-02-07T17:54:06Z

docs/machine-requests/overview.mdx

+  const { token } = await clerkClient.machineTokens.create({
+    machineId: 'mch_cron',
+    claims: {
+      permissions: ['read', 'write'],


Some explanation around what the purpose of this is would be good, my guess is for the route to check that not only is the POST request authenticated but that its also authorized? I feel it would be beneficial to have down in the example below pulling these claims out and checking against them.

NWylynko · 2025-02-07T18:17:42Z

docs/machine-requests/machine-tokens.mdx

+
+Every machine token you create needs to be associated with a `machine_id`. You can pick any value for the `machine_id` as long as it meets the following requirements:
+
+- It must be prefixed with `mch_`


Since I am already explicitly calling clerkClient.machineTokens.create couldn't the sdk just prefix the id with mch_ for me? If it has to be this way then I think this is pretty clearly outlined. The types for this field should definitely be `mch_${string}` to enforce this.

NWylynko · 2025-02-07T18:21:39Z

docs/machine-requests/machine-tokens.mdx

+  - ❌ `MCH_UPPERCASE`
+
+### Claims
+


An example here of how this works would be helpful, even better if the example showed how to type the claims, or validate them with a schema.

NWylynko · 2025-02-07T18:42:51Z

docs/machine-requests/machine-tokens.mdx

+
+### Machine ID
+
+Every machine token you create needs to be associated with a `machine_id`. You can pick any value for the `machine_id` as long as it meets the following requirements:


It's not necessarily clear why a machine_id is required. Is it purely an internal thing for clerk? Does this give us controls in clerk dashboard to "ban" a machine? Are we supposed to validate the machine_id where we are receiving the request?

Ben2W added the deploy-preview label Nov 20, 2024

Ben2W force-pushed the ben/machine-tokens branch from f25d216 to d6aa27f Compare November 21, 2024 00:40

Ben2W force-pushed the ben/machine-tokens branch from ff5ca46 to 155ff57 Compare January 28, 2025 20:21

Ben2W added Blocked and removed deploy-preview labels Jan 28, 2025

Ben2W force-pushed the ben/machine-tokens branch from 155ff57 to cfb62cb Compare January 28, 2025 20:23

Ben2W added deploy-preview and removed Blocked labels Jan 28, 2025

Ben2W marked this pull request as ready for review January 29, 2025 08:50

Ben2W requested a review from a team as a code owner January 29, 2025 08:51

Ben2W marked this pull request as draft January 29, 2025 08:55

Ben2W marked this pull request as ready for review January 29, 2025 08:59

Ben2W force-pushed the ben/machine-tokens branch 2 times, most recently from c43da27 to ee56c1d Compare February 3, 2025 21:42

jakobevangelista reviewed Feb 3, 2025

View reviewed changes

docs/machine-requests/overview.mdx Outdated Show resolved Hide resolved

jakobevangelista reviewed Feb 3, 2025

View reviewed changes

docs/machine-requests/overview.mdx Outdated Show resolved Hide resolved

jakobevangelista reviewed Feb 3, 2025

View reviewed changes

jakobevangelista reviewed Feb 4, 2025

View reviewed changes

docs/machine-requests/manual-jwt.mdx Outdated Show resolved Hide resolved

brkalow reviewed Feb 4, 2025

View reviewed changes

Ben2W added 5 commits February 6, 2025 19:11

adding docs pages

e788e1f

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

small changes

f205ee7

changing backend requests section to session requests

9529cf1

editing session requests slightly

adding manual jwt verification

c7a9659

improving authenticateRequest docs page updating auth object type editing nextjs auth docs page Removing unnecessary preface

moving to a backend requests section

7e883d0

Ben2W force-pushed the ben/machine-tokens branch from ee56c1d to 7e883d0 Compare February 7, 2025 03:11

Ben2W and others added 3 commits February 6, 2025 19:12

Update docs/machine-requests/overview.mdx

11302aa

Co-authored-by: Jakob Evangelista <[email protected]>

Update docs/machine-requests/overview.mdx

e5630d5

Co-authored-by: Jakob Evangelista <[email protected]>

naming function in example

3707eb0

Ben2W and others added 5 commits February 6, 2025 19:49

making api request the first example

66288eb

Update docs/machine-requests/overview.mdx

9ef717e

Co-authored-by: Bryce Kalow <[email protected]>

Update docs/machine-requests/overview.mdx

65737d2

Co-authored-by: Bryce Kalow <[email protected]>

Update docs/machine-requests/manual-jwt.mdx

0caaaef

Co-authored-by: Bryce Kalow <[email protected]>

Update docs/machine-requests/manual-jwt.mdx

d029ef2

Co-authored-by: Bryce Kalow <[email protected]>

Ben2W force-pushed the ben/machine-tokens branch from 8ac5001 to d029ef2 Compare February 7, 2025 03:52

Ben2W and others added 4 commits February 6, 2025 19:58

Bryce changes

4b4c812

fixing broken links

36ab5ba

Update docs/machine-requests/overview.mdx

33a34da

Co-authored-by: Bryce Kalow <[email protected]>

Update docs/machine-requests/overview.mdx

0b036b1

Co-authored-by: Bryce Kalow <[email protected]>

Ben2W force-pushed the ben/machine-tokens branch from 3128c79 to 0b036b1 Compare February 7, 2025 06:51

minor changes

d7da65d

NWylynko reviewed Feb 7, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Machine Token Docs #1725

feat: Machine Token Docs #1725

Ben2W commented Nov 20, 2024 •

edited

Loading

github-actions bot commented Nov 20, 2024

github-actions bot commented Jan 28, 2025

jakobevangelista Feb 3, 2025

Ben2W Feb 7, 2025

Ben2W commented Feb 7, 2025

jakobevangelista commented Feb 7, 2025

NWylynko Feb 7, 2025

NWylynko Feb 7, 2025

NWylynko Feb 7, 2025

NWylynko Feb 7, 2025

NWylynko Feb 7, 2025


		#### Examples

		<Tabs items={['Next.js Middleware', 'Next.js API Route']}>


		#### Examples

		<Tabs items={['Next.js API Route', 'Next.js Middleware']}>


		Every machine token you create needs to be associated with a `machine_id`. You can pick any value for the `machine_id` as long as it meets the following requirements:

		- It must be prefixed with `mch_`


		### Machine ID

		Every machine token you create needs to be associated with a `machine_id`. You can pick any value for the `machine_id` as long as it meets the following requirements:

feat: Machine Token Docs #1725

Are you sure you want to change the base?

feat: Machine Token Docs #1725

Conversation

Ben2W commented Nov 20, 2024 • edited Loading

Created the following machine request pages:

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

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

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

Checklist

github-actions bot commented Nov 20, 2024

github-actions bot commented Jan 28, 2025

jakobevangelista Feb 3, 2025

Choose a reason for hiding this comment

Ben2W Feb 7, 2025

Choose a reason for hiding this comment

Ben2W commented Feb 7, 2025

jakobevangelista commented Feb 7, 2025

NWylynko Feb 7, 2025

Choose a reason for hiding this comment

NWylynko Feb 7, 2025

Choose a reason for hiding this comment

NWylynko Feb 7, 2025

Choose a reason for hiding this comment

NWylynko Feb 7, 2025

Choose a reason for hiding this comment

NWylynko Feb 7, 2025

Choose a reason for hiding this comment

Ben2W commented Nov 20, 2024 •

edited

Loading