Terminology
A consistent terminology should be used across all user interactions with Clerk's services (e.g., SDKs, documentation, dashboard, error messages, support). The following list includes the most common terms and their explanations. Use these terms in your SDKs, documentation, and support materials.
| Name | Description |
|---|---|
| Client | A client represents the current device or software accessing an application such as your web browser, native application, Chrome Extension, or Electron app. |
| Session | A session is a secure representation of the authentication state of the current user. Each client can hold multiple sessions on the same device. This is identical to how Gmail works in a browser. |
| User | A user represents the current user of the session. The User object holds all the basic user information e.g. name, email addresses, phone numbers, etc… including their public, private, and unsafe metadata. |
| Organization | An organization represents the current organization of the session. Users can belong to many organizations. One of them will be the active organization of the session. |
| FAPI | Frontend API of Clerk. Example: https://random-name.clerk.accounts.dev (Production example: https://clerk.yourdomain.com). FAPI is the primary API for Clerk’s UI components. Every Clerk development/production instance has a dedicated FAPI. This is the authentication, session, user & organization management API you or your users will interact with. |
| BAPI | Backend API of Clerk. Currently set to https://api.clerk.com. A restful CRUD API for the server-side. |
| Secret key | Your app’s secret key for use in the backend. Do not expose this on the frontend with a public environment variable. Allows for CRUD operations. |
| Publishable key | Your app’s publishable key for use in the frontend. |
| Instances | When creating an app, you’re provided with two instances: Development and Production. Learn more. |
| Hotloading ClerkJS | @clerk/clerk-js, or ClerkJS, is the foundational JavaScript library for all frontend JS SDKs, e.g. used in @clerk/clerk-react. When you install @clerk/clerk-react through npm, you don’t install @clerk/clerk-js. Instead, once the React code is executed in the browser, the React SDK adds a <script> tag to load ClerkJS from a CDN. Clerk internally calls this “hotloading”. |
| UI components | All components displayed in the component reference and available through the Clerk class. |
| Authorization header verification | This refers to the HTTP Authorization request header. Clerk uses this HTTP header instead of the __client cookie for secure communication with the FAPI in non-standard web browser environments. For example, in React Native apps, Chrome extensions, and hybrid apps like Electron, the __client JWT will be stored in a secure storage provided by the platform and injected into the HTTP header of each FAPI request. |
| Handshake | The client handshake is a mechanism that is used to resolve a request’s authentication state from “unknown” to definitively signed in or signed out. Clerk’s session management architecture relies on a short-lived session JWT to validate requests, along with a long-lived session that is used to keep the session JWT fresh by interacting with the FAPI. The long-lived session token is stored in an HttpOnly cookie associated with the FAPI domain. If a short-lived session JWT 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 the handshake. |
Cookies
Clerk is using cookies in order to keep user sessions alive. It's useful to know about these when debugging issues.
Development instance cookies
| Cookie Name | Description |
|---|---|
__clerk_db_jwt | The Development Browser JWT. Helps Clerk sync the session between the development instance domain, localhost, and the Clerk FAPI and Account Portal domain, https://name.accounts.dev. |
__client_uat | uat stands for Updated At and helps Clerk to check if the user session is still valid. It is set by clerk-js on the client-side. |
__session | A short-lived session JWT to validate requests in your application or your API. |
Production instance cookies
| Cookie Name | Description |
|---|---|
__client | This is a long-lived HttpOnly cookie that is used to issue short-lived session JWTs. It is set by the Clerk FAPI. |
__client_uat | uat stands for Updated At and helps Clerk to check if the user session is still valid. It is set by the Clerk FAPI. |
__session | A short-lived session JWT to validate requests in your application or your API. |
Clerk is using other non-persistent cookies (e.g. __clerk_handshake) for internal mechanisms but for the sake of creating a new SDK from scratch, you don't need to worry about those.
Feedback
Last updated on