Request authentication

A request is considered “authenticated” when the backend can securely identify the user and device that is making the request. The reasons for making authenticated requests to the backend include:

• Associating the user with the action being performed
• Ensuring the user has permission to make the request
• Keeping an audit log of which device the user is performing actions from

In order to authenticate the user on the backend using Clerk's SDK, the short-lived session token needs to be passed to the server.

Frontend requests

To make authenticated requests from the frontend, the approach differs based on whether your client and server are on the same origin.

The origin includes the protocol, hostname, and port (optional):

<protocol>//<hostname>[:<port>]

Same-origin

For same-origin requests, refer to our guide on making same-origin requests.

Cross-origin

For cross-origin requests, refer to our guide on making cross-origin requests.

Backend requests

Clerk provides various middleware packages to set the session property for easy access. These packages can also require a session to be available on the current request. Choose the guide based on the language or framework you're using:

• Next.js
• Gatsby
• Node.js / Express
• Go
• Ruby on Rails / Rack

If there is not middleware available for your preferred language or framework, you can extract the session token manually.

Same-origin

For same-origin requests, the session token is included in the __session cookie and you can use an open source library to parse the cookie on the back-end.

Cross-origin

For cross-origin requests, the Bearer token inside the Authorization header contains the session token.

You can read more about manual JWT verification for additional information.

Required headers

The following headers are required for Clerk to authenticate a request. It contains information that Clerk uses to determine whether a request is in a signed in or signed out state, or if a handshake must be performed.

• Authorization(opens in a new tab) – This should be the user's session token.
• Accept(opens in a new tab)
• Host(opens in a new tab)
• Origin(opens in a new tab)
• Referer(opens in a new tab)
• Sec-Fetch-Dest(opens in a new tab)
• User-Agent(opens in a new tab)
• X-Forwarded-Host(opens in a new tab)
• X-Forwarded-Proto(opens in a new tab)
  • Alternatively, you can use CloudFront-Forwarded-Proto(opens in a new tab)

Last updated on September 15, 2023