Skip to content

Commit

Permalink
grammatical updates
Browse files Browse the repository at this point in the history
  • Loading branch information
alexisintech committed Feb 5, 2024
1 parent b349829 commit 4f9c0b1
Showing 1 changed file with 7 additions and 7 deletions.
14 changes: 7 additions & 7 deletions docs/concepts/how-clerk-works.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Clerk is a powerful authentication and user management system that allows you to
Clerk provices both development and production environments for your app. Production instances are used for production, pre-production, or staging environments with fixed domains. Production instances offer the strongest security and performance guarantees. Development instances contain certain trade-offs meant to support ease of active development.

<Callout type="warning">
Never use a development instance in a production environment. Development instances dont have strong security guarantees.
Never use a development instance in a production environment. Development instances don't have strong security guarantees.
</Callout>

## Main objects
Expand Down Expand Up @@ -56,28 +56,28 @@ Clerk's Frontend API is responsible for maintaining the authentication state of

### Clerk cookies

Clerks Frontend API uses two cookies for session management in production instances:
Clerk's Frontend API uses two cookies for session management in production instances:

* `__client` cookie: a long-lived session that is used to keep the the session JWT fresh by interacting with the Frontend API.
* `__session` cookie: a short-lived session JWT to validate requests on your application or your API.

#### The `__client` cookie

The `__client` cookie is set on Clerk Frontend API (for example `https://clerk.<example.com>`) for each instance. Its HTTP-only, first-party, and secure. It contains a long-lived client JWT that lasts 7 days by default. The duration is configurable in the Clerk Dashboard's [Sessions page](https://dashboard.clerk.com/last-active?path=sessions). The JWT identifies the current client (browser, native application, or chrome extension) and sets the current active sessions.
The `__client` cookie is set on Clerk Frontend API (for example `https://clerk.<example.com>`) for each instance. It's HTTP-only, first-party, and secure. It contains a long-lived client JWT that lasts 7 days by default. The duration is configurable in the Clerk Dashboard's [Sessions page](https://dashboard.clerk.com/last-active?path=sessions). The JWT identifies the current client (browser, native application, or chrome extension) and sets the current active sessions.

#### The `__session` cookie

The `__session` cookie is set on the host application that is secured by Clerk (for example `https://dashboard.<example.com>`). Its a JS cookie, its secure, and it contains a short-lived session JWT that lasts 60 seconds. This JWT contains the current session, user, and organization identifiers and must be sent to the application API to authenticate API requests. In SSR, the `__session` cookie travels automatically to the server. ClerkJS ensures that the `__session` cookie is automatically refreshed in Client Side Rendering (CSR) and Server Side Rendering (SSR), ensuring a fresh session is always available.
The `__session` cookie is set on the host application that is secured by Clerk (for example `https://dashboard.<example.com>`). It's a JS cookie, it's secure, and it contains a short-lived session JWT that lasts 60 seconds. This JWT contains the current session, user, and organization identifiers and must be sent to the application API to authenticate API requests. In SSR, the `__session` cookie travels automatically to the server. ClerkJS ensures that the `__session` cookie is automatically refreshed in Client Side Rendering (CSR) and Server Side Rendering (SSR), ensuring a fresh session is always available.

However, if a `__session` cookie is expired on a request to an applications backend, the SDK doesnt know if the session has ended, or if a new short-lived JWT needs to be issued. When an SDK gets into this state, it triggers Clerk's client handshake.
However, if a `__session` cookie is expired on a request to an application's backend, the SDK doesn't know if the session has ended, or if a new short-lived JWT needs to be issued. When an SDK gets into this state, it triggers Clerk's client handshake.

#### The `__client_uat` cookie

The `__client_uat` cookie is set on the host application that is secured by Clerk and hints Clerk SDKs about the timestamp of the latest authentication update of the current client.

### The client handshake

Clerk uses a client handshake mechanism to resolve a requests authentication state from unknown (`handshake`) to `signed-in` or `signed-out`.
Clerk uses a client handshake mechanism to resolve a request's authentication state from unknown (`handshake`) to `signed-in` or `signed-out`.

With this handshake, Clerk can resolve authentication state on the backend and ensure the request is properly handled as signed in or out, instead of being in a potentially unknown state. The handshake flow relies on redirects to exchange session information between FAPI and the application, ensuring the resolution of unknown authentication states minimizes performance impact and behaves consistently across different framework and language implementations.

Expand All @@ -98,7 +98,7 @@ Every Frontend API request returns a response payload that contains two top leve
The `/v1/client/sessions/:id/tokens` endpoint refreshes the Clerk session tokens and is an exception to this format.
</Callout>

The `response` key contains the resource or resources of each endpoint. The `client` key contains the client piggybacking payload. The client object identifies the current device and contains all sessions, users, and organization data for the current device (see [Main Objects](#main-objects) section).
The `response` key contains the resource or resources of each endpoint. The `client` key contains the client piggybacking payload. The `client` object identifies the current device and contains all sessions, users, and organization data for the current device (see [Main Objects](#main-objects) section).

This is effectively the necessary frontend state for ClerkJS and powers the JS SDKs, the [React hooks](/docs/references/react/use-user), and [Clerk components](/docs/components/overview). It is a best-effort way for the backend to update the frontend state on every Frontend API request.

Expand Down

0 comments on commit 4f9c0b1

Please sign in to comment.