Skip to content

Latest commit

 

History

History
223 lines (153 loc) · 19.6 KB

README.md

File metadata and controls

223 lines (153 loc) · 19.6 KB
Raw

Sessions

(sessions)

Overview

The Session object is an abstraction over an HTTP session. It models the period of information exchange between a user and the server. Sessions are created when a user successfully goes through the sign in or sign up flows. https://clerk.com/docs/reference/clerkjs/session

Available Operations

list

Returns a list of all sessions. The sessions are returned sorted by creation date, with the newest sessions appearing first. Deprecation Notice (2024-01-01): All parameters were initially considered optional, however moving forward at least one of client_id or user_id parameters should be provided.

Example Usage

import clerk_backend_api
from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.sessions.list(client_id="client_123", user_id="user_456", status=clerk_backend_api.QueryParamStatus.ACTIVE, limit=20, offset=10)

    if res is not None:
        # handle response
        pass

Parameters

Parameter Type Required Description Example
client_id Optional[str] ➖ List sessions for the given client client_123
user_id Optional[str] ➖ List sessions for the given user user_456
status Optional[models.QueryParamStatus] ➖ Filter sessions by the provided status active
limit Optional[int] ➖ Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.		 20
offset Optional[int] ➖ Skip the first offset results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with limit.		 10
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

List[models.Session]

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 401, 422 application/json
models.SDKError 4XX, 5XX */*

get

Retrieve the details of a session

Example Usage

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.sessions.get(session_id="sess_1234567890abcdef")

    if res is not None:
        # handle response
        pass

Parameters

Parameter Type Required Description Example
session_id str ✔️ The ID of the session sess_1234567890abcdef
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Session

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 401, 404 application/json
models.SDKError 4XX, 5XX */*

revoke

Sets the status of a session as "revoked", which is an unauthenticated state. In multi-session mode, a revoked session will still be returned along with its client object, however the user will need to sign in again.

Example Usage

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.sessions.revoke(session_id="sess_1234567890abcdef")

    if res is not None:
        # handle response
        pass

Parameters

Parameter Type Required Description Example
session_id str ✔️ The ID of the session sess_1234567890abcdef
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Session

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 401, 404 application/json
models.SDKError 4XX, 5XX */*

verify

Returns the session if it is authenticated, otherwise returns an error. WARNING: This endpoint is deprecated and will be removed in future versions. We strongly recommend switching to networkless verification using short-lived session tokens, which is implemented transparently in all recent SDK versions (e.g. NodeJS SDK). For more details on how networkless verification works, refer to our Session Tokens documentation.

⚠️ DEPRECATED: This will be removed in a future release, please migrate away from it as soon as possible.

Example Usage

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.sessions.verify(session_id="sess_w8q4g9s60j28fghv00f3", token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoic2Vzc193OHF4ZzZzNm9qMjhmZ2h2MDBmMyIsImlhdCI6MTU4MjY0OTg2Mn0.J4KP2L6bEZ6YccHFW4E2vKbOLw_mmO0gF_GNRw-wtLM")

    if res is not None:
        # handle response
        pass

Parameters

Parameter Type Required Description Example
session_id str ✔️ The ID of the session sess_w8q4g9s60j28fghv00f3
token Optional[str] ➖ The JWT that is sent via the __session cookie from your frontend.
Note: this JWT must be associated with the supplied session ID.		 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoic2Vzc193OHF4ZzZzNm9qMjhmZ2h2MDBmMyIsImlhdCI6MTU4MjY0OTg2Mn0.J4KP2L6bEZ6YccHFW4E2vKbOLw_mmO0gF_GNRw-wtLM
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.Session

Errors

Error Type Status Code Content Type
models.ClerkErrors 400, 401, 404, 410 application/json
models.SDKError 4XX, 5XX */*

create_token_from_template

Creates a JSON Web Token(JWT) based on a session and a JWT Template name defined for your instance

Example Usage

from clerk_backend_api import Clerk

with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as s:
    res = s.sessions.create_token_from_template(session_id="ses_123abcd4567", template_name="custom_hasura")

    if res is not None:
        # handle response
        pass

Parameters

Parameter Type Required Description Example
session_id str ✔️ The ID of the session ses_123abcd4567
template_name str ✔️ The name of the JWT Template defined in your instance (e.g. custom_hasura). custom_hasura
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.CreateSessionTokenFromTemplateResponseBody

Errors

Error Type Status Code Content Type
models.ClerkErrors 401, 404 application/json
models.SDKError 4XX, 5XX */*