feat: Machine Token Docs #1725
Open
feat: Machine Token Docs #1725
Conversation
This file contains 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
|
Hey, here’s your docs preview: https://clerk.com/docs/pr/1725 |
Ben2W
force-pushed
the
ben/machine-tokens
branch
from
f25d216 to
d6aa27f
Compare
Ben2W
force-pushed
the
ben/machine-tokens
branch
from
ff5ca46 to
155ff57
Compare
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
Ben2W
force-pushed
the
ben/machine-tokens
branch
from
155ff57 to
cfb62cb
Compare
|
Hey, here’s your docs preview: https://clerk.com/docs/pr/1725 |
Ben2W
force-pushed
the
ben/machine-tokens
branch
from
87e98ac to
c43da27
Compare
editing session requests slightly
improving authenticateRequest docs page updating auth object type editing nextjs auth docs page Removing unnecessary preface
Ben2W
force-pushed
the
ben/machine-tokens
branch
from
c43da27 to
ee56c1d
Compare
| import { runCronJob } from './cronJob'; | ||
|
|
||
| export const POST = async () => { | ||
| const { isMachineAuthenticated } = await auth({ entity: 'machine' }); |
There was a problem hiding this comment.
Suggested change
| const { isMachineAuthenticated } = await auth({ entity: 'machine' }); | |
| const { machineId } = await auth({ entity: 'machine' }); |
this works the same way as user auth() where you should check for machineId
| export const POST = async () => { | ||
| const { isMachineAuthenticated } = await auth({ entity: 'machine' }); | ||
|
|
||
| if (!isMachineAuthenticated) { |
There was a problem hiding this comment.
Suggested change
| if (!isMachineAuthenticated) { | |
| if (!machineId) { |
to satisfy the change to machineId
|
|
||
| #### Examples | ||
|
|
||
| <Tabs items={['Next.js Middleware', 'Next.js API Route']}> |
There was a problem hiding this comment.
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
| ```tsx | ||
| import jwt from 'jsonwebtoken' | ||
|
|
||
| export default async function (req: Request, res: Response) { |
There was a problem hiding this comment.
should probably have a name on this function
brkalow
reviewed
Feb 4, 2025
|
|
||
| ## Creating Machine Requests | ||
|
|
||
| You can create a machine token using the [clerk backend api](https://clerk.com/docs/reference/backend-api/tag/machine-tokens). Then use the created token in the `Authorization` header of outgoing request. |
There was a problem hiding this comment.
Suggested change
| You can create a machine token using the [clerk backend api](https://clerk.com/docs/reference/backend-api/tag/machine-tokens). Then use the created token in the `Authorization` header of outgoing request. | |
| You can create a machine token using the [Clerk Backend API](https://clerk.com/docs/reference/backend-api/tag/machine-tokens). Then use the created token in the `Authorization` header of outgoing requests. |
| You can create a machine token using the [clerk backend api](https://clerk.com/docs/reference/backend-api/tag/machine-tokens). Then use the created token in the `Authorization` header of outgoing request. | ||
|
|
||
| > [!WARNING] | ||
| > Because creating machine tokens using [clerk backend api](https://clerk.com/docs/reference/backend-api/tag/machine-tokens), it is subject to the [Backend API rate limits](/docs/rate-limits). |
There was a problem hiding this comment.
Suggested change
| > Because creating machine tokens using [clerk backend api](https://clerk.com/docs/reference/backend-api/tag/machine-tokens), it is subject to the [Backend API rate limits](/docs/rate-limits). | |
| > Creating machine tokens uses the Clerk Backend API, and so it is subject to the [Backend API rate limits](/docs/rate-limits). |
| You can verify machine tokens in two ways: | ||
|
|
||
| 1. Using Clerk's Backend SDKs (recommended) | ||
| 2. Manually verifying the machine token JWT using your instance's public key. |
There was a problem hiding this comment.
Suggested change
| 2. Manually verifying the machine token JWT using your instance's public key. | |
| 2. Manually verifying the machine token JWT using your instance's Public Key. |
|
|
||
| ## Verifying Machine Requests | ||
|
|
||
| For a machine request to be valid, it must include a valid [machine token](/docs/machine-requests/machine-tokens) in the Bearer `Authorization` header. |
There was a problem hiding this comment.
Are we capitalizing Machine Request? Let's make a decision and make it consistent through. Same for Machine Token.
Suggested change
| For a machine request to be valid, it must include a valid [machine token](/docs/machine-requests/machine-tokens) in the Bearer `Authorization` header. | |
| For a Machine Request to be valid, it must include a valid [machine token](/docs/machine-requests/machine-tokens) in the Bearer `Authorization` header. |
|
|
||
| ### Using Clerk's Backend SDKs | ||
|
|
||
| By default, authenticating requests, will default to authenticating user [session requests](/docs/session-requests/overview). |
There was a problem hiding this comment.
Suggested change
| By default, authenticating requests, will default to authenticating user [session requests](/docs/session-requests/overview). | |
| By default, authenticating requests will default to authenticating them as user [session requests](/docs/session-requests/overview). |
|
|
||
| #### Examples | ||
|
|
||
| <Tabs items={['Next.js Middleware', 'Next.js API Route']}> |
There was a problem hiding this comment.
I don't think we want to lead with middleware, auth should be done as close to the resource being protected as possible.
| description: Learn how to manually verify Clerk-generated machine tokens (JWTs). | ||
| --- | ||
|
|
||
| Your Clerk-generated [machine tokens](/docs/machine-requests/machine-tokens) are essentially JWTs which are signed using your instance's private key and can be verified using your instance's public key. |
There was a problem hiding this comment.
Suggested change
| Your Clerk-generated [machine tokens](/docs/machine-requests/machine-tokens) are essentially JWTs which are signed using your instance's private key and can be verified using your instance's public key. | |
| Your Clerk-generated [machine tokens](/docs/machine-requests/machine-tokens) are JWTs which are signed using your instance's private key and can be verified using your instance's public key. |
|
|
||
| Your Clerk-generated [machine tokens](/docs/machine-requests/machine-tokens) are essentially JWTs which are signed using your instance's private key and can be verified using your instance's public key. | ||
|
|
||
| For every machine request, you must validate the token to ensure it hasn't expired or been tampered with (i.e., it's authentic and secure). Additionally, you likely want to differentiate between machine and user requests. If these validations succeed, then the machine is authenticated to your application. |
There was a problem hiding this comment.
Suggested change
| For every machine request, you must validate the token to ensure it hasn't expired or been tampered with (i.e., it's authentic and secure). Additionally, you likely want to differentiate between machine and user requests. If these validations succeed, then the machine is authenticated to your application. | |
| For every machine request, you must validate the token to ensure it hasn't expired or been tampered with (i.e., it's authentic and secure). Additionally, you might want to differentiate between machine and user requests within your application. If these validations succeed, then the machine is authenticated and granted access to your application. |
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.
Currently all customer-facing tokens are session tokens. We are adding
machine tokenswhich is another customer-facing token. This PR adds documentation on: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.
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:
Slack thread:
https://clerkinc.slack.com/archives/C01QFRQNHSN/p1738141182851989
Checklist