Skip to content

Commit b11fcdf

Browse files
authored
Update core concepts guide (#2669)
1 parent 6f93be7 commit b11fcdf

File tree

3 files changed

+23
-11
lines changed

3 files changed

+23
-11
lines changed

docs/getting-started/core-concepts.mdx

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -39,34 +39,46 @@ To get started, see the [configuration docs](/docs/guides/configure/auth-strateg
3939

4040
## Building your application
4141

42-
The Clerk JavaScript SDK, or ClerkJS, is where Clerk all started. It is the core SDK that powers all other JavaScript SDKs, including React and Next.js. The following sections will introduce you to the main objects that make up ClerkJS.
42+
### Session token
4343

44-
### Clerk
44+
When a user is authenticated in your application, Clerk generates a short-lived session token that you can use to authenticate requests to your backend. This token is a JSON Web Token (JWT) that contains information about the user and their session.
45+
46+
Read more about Clerk session tokens and how they work in [the guide on how Clerk works](/docs/guides/how-clerk-works/overview).
47+
48+
### Key Clerk objects
49+
50+
The Clerk JavaScript SDK, or ClerkJS, is where Clerk all started. It is the core SDK that powers all other JavaScript SDKs, including React and Next.js. As you build, you'll likely interact with the following objects.
51+
52+
#### Clerk
4553

4654
The [`Clerk`](/docs/reference/javascript/clerk) class is the main entry point for the Clerk JavaScript SDK. All other objects are accessible from the `Clerk` object. As you're building your application, you'll likely interact with these objects, either directly or through helpers provided by the other SDKs, like React hooks or Vue composables.
4755

48-
### Client
56+
#### Client
4957

5058
A client represents the current device or software accessing an application such as your web browser, native application, or Chrome Extension. It is represented by the [`Client`](/docs/reference/javascript/client) object.
5159

52-
### Session
60+
#### Session
5361

5462
A session is a secure representation of the authentication state of the current user. Each client can hold multiple sessions on the same device. It is represented by the [`Session`](/docs/reference/javascript/session) object.
5563

56-
### User
64+
#### User
5765

5866
The [`User`](/docs/reference/javascript/user) object represents the current user of the session. It holds all the basic user information such as the user's name, email addresses, and phone numbers, and including their public, private, and unsafe metadata.
5967

60-
### Organization
68+
#### Organization
6169

6270
Organizations are a flexible and scalable way to manage users and their access to resources within your Clerk application. With organizations, you can assign specific roles and permissions to users, making them useful for managing projects, coordinating teams, or facilitating partnerships.
6371

64-
Users can belong to many organizations. One of them will be the ["active organization"](/docs/guides/organizations/overview#active-organization) of the session. It is represented by the [`Organization`](/docs/reference/javascript/organization) object. To learn about organizations, see the [dedicated guide](/docs/guides/organizations/overview).
72+
Users can belong to many organizations. One of them will be the [active organization](!active-organization) of the session. It is represented by the [`Organization`](/docs/reference/javascript/organization) object. To learn about organizations, see the [dedicated guide](/docs/guides/organizations/overview).
6573

66-
### Sign in
74+
#### Sign in
6775

6876
The [`SignIn`](/docs/reference/javascript/sign-in) object holds the state of the current sign-in and provides helper methods to navigate and complete the sign-in process. It is used to manage the sign-in lifecycle, including the first and second factor verification, and the creation of a new session.
6977

70-
### Sign up
78+
#### Sign up
7179

7280
The [`SignUp`](/docs/reference/javascript/sign-up) object holds the state of the current sign-up and provides helper methods to navigate and complete the sign-up process. Once a sign-up is complete, a new user is created.
81+
82+
## Deep dive
83+
84+
For a deeper dive into how Clerk works, like how our authentication model works, see the [dedicated guide](/docs/guides/how-clerk-works/overview).

docs/guides/organizations/overview.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ Verified domains can be used to streamline enrollment into an organization. For
5858
In the Clerk Dashboard, there are two types of workspaces:
5959

6060
- **Personal account**: A personal account/workspace is a user's unique, individual space, independent of any organization.
61-
- **Organization workspace**: An organization workspace is owned and managed by an organization, which can have multiple members, also known as collaborators. The organization workspace that a user is currently viewing is called the [active organization](/docs/guides/organizations/overview#active-organization).
61+
- **Organization workspace**: An organization workspace is owned and managed by an organization, which can have multiple members, also known as collaborators. The organization workspace that a user is currently viewing is called the [active organization](!active-organization).
6262

6363
Most multi-tenant applications want every user to be part of an organization rather than operating in an isolated personal account. Accordingly, **personal accounts are disabled by default** once you enable organizations. After signing up, [a user must create or join an organization before they can proceed](/docs/guides/configure/session-tasks).
6464

docs/guides/sessions/session-tokens.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ Read more about Clerk session tokens and how they work in [the guide on how Cler
9898
| `sid` | session ID | The ID of the current session. | `sess_123` |
9999
| `sub` | subject | The ID of the current user of the session. See [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2) for more information. | `user_123` |
100100

101-
The following claims are only included if the user is part of an organization and that organization is [active](/docs/guides/organizations/overview#active-organization):
101+
The following claims are only included if the user is part of an organization and that organization is [active](!active-organization):
102102

103103
| Claim | Abbreviation expanded | Description | Example |
104104
| - | - | - | - |

0 commit comments

Comments
 (0)