Docs

Session

The Session object is an abstraction over an HTTP session. It models the period of information exchange between a user and the server.

The Session object includes methods for recording session activity and ending the session client-side. For security reasons, sessions can also expire server-side.

As soon as a User signs in, Clerk creates a Session for the current Client. Clients can have more than one sessions at any point in time, but only one of those sessions will be active.

In certain scenarios, a session might be replaced by another one. This is often the case with mutli-session applications.

All sessions that are expired, removed, replaced, ended or abandoned are not considered valid.

Note

For more details regarding the different session states, see our documentation on session management.

Properties

  • Name
    id
    Type
    string
    Description

    A unique identifier for the session.

  • Name
    user
    Type
    User
    Description

    The user associated with the session.

  • Name
    publicUserData
    Type
    PublicUserData
    Description

    Public information about the user that this session belongs to.

  • Name
    status
    Type
    SessionStatus
    Description

    The current state of the session.

  • Name
    lastActiveAt
    Type
    Date
    Description

    The time the session was last active on the Client.

  • Name
    abandonAt
    Type
    Date
    Description

    The time when the session was abandoned by the user.

  • Name
    expireAt
    Type
    Date
    Description

    The time the session expires and will cease to be active.

  • Name
    updatedAt
    Type
    Date
    Description

    The last time the session recorded activity of any kind.

  • Name
    createdAt
    Type
    Date
    Description

    The time the session was created.

  • Name
    lastActiveToken
    Type
    TokenResource | null
    Description

    The last active token for the session

  • Name
    lastActiveOrganizationId
    Type
    string | null
    Description

    The last active organization identifier

  • Name
    actor
    Type
    ActJWTClaim | null
    Description

    The JWT actor for the session

Methods

end()

Marks the session as ended. The session will no longer be active for this Client and its status will become ended.

function end(): Promise<Session>;

remove()

Marks the session as removed. The session will no longer be active for this Client and its status will become removed.

function remove(): Promise<Session>;

touch()

Touches the session, signifying some kind of user activity. Use this method to record any updates to user activity.

function touch(): Promise<Session>;

getToken()

Retrieves the user's session token for the default Clerk token or the given template.

This method uses a cache so a network request will only be made if the token in memory has expired. The TTL for a Clerk token is one minute.

Tokens can only be generated if the user is signed in.

function getToken(options?: GetTokenOptions): Promise<string | null>;

GetTokenOptions

  • Name
    leewayInSeconds
    Type
    number
    Description

    The number of seconds to allow the token to be cached for.

  • Name
    template?
    Type
    string
    Description

    The name of the JWT template from the Clerk Dashboard to generate a new token from.
    E.g. 'firebase', 'grafbase', or your custom template's name.

  • Name
    throwOnError?
    Type
    boolean
    Description

    Whether to throw an error or return an empty string, if an error occurs.

  • Name
    skipCache?
    Type
    boolean
    Description

    Whether to skip the cache lookup and force a call to the server instead, even within the TTL. Useful if the token claims are time-sensitive or depend on data that can be updated (e.g. user fields).
    Defaults to false.

getToken() example

main.js
import Clerk from '@clerk/clerk-js';

// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_KEY');
await clerk.load();

if (clerk.user) {
  await clerk.session.getToken({ template: "Test" })
    .then((res) => console.log(res))
    .catch((error) => console.log("An error occurred:", error.errors));
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;

  const signInDiv = document.getElementById("sign-in");

  clerk.mountSignIn(signInDiv);
}
index.html
<div id="app"></div>

<!-- Initialize Clerk with your
Clerk Publishable key and Frontend API URL -->
<script
  async
  crossorigin="anonymous"
  data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://YOUR_FRONTEND_API_URL/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
  type="text/javascript"
></script>

<script>
  window.addEventListener('load', async function () {
    await Clerk.load();

    if (Clerk.user) {
      await Clerk.session.getToken({ template: "Test" })
        .then((res) => console.log(res))
        .catch((error) => console.log("An error occurred:", error.errors));
    } else {
      document.getElementById("app").innerHTML = `
        <div id="sign-in"></div>
      `;

      const signInDiv = document.getElementById("sign-in");

      Clerk.mountSignIn(signInDiv);
    }
  });
</script>
try {
  await Clerk.session.getToken({ template: 'my-template-1' }) // => "eyJhbGciOiJSUzI1NiIsImtpZC..."
} catch(e) {
    // handle error
}

checkAuthorization()

Checks if the user is authorized for the specified role or permission.

function checkAuthorization(param: CheckAuthorizationParams) => boolean;

CheckAuthorizationParams

type CheckAuthorizationParams =
  | {
      role: ClerkDefaultRole | CustomRole;
      permission?: never;
    }
  | {
      role?: never;
      permission: ClerkDefaultPermission | CustomPermission;
    };
  • Name
    role
    Type
    string
    Description

    Accepts role key

  • Name
    permission
    Type
    string
    Description

    Accepts permission key

Feedback

What did you think of this content?
Edit this page on GitHub