OTPLoginService

class OTPLoginService[source]

Methods

confirm

Verify the OTP code.

create

Create an OTP login session and send a code to the given email.

list

List users matching this OTP session (paginated).

select

Select a user from the multi-user list and log in.
confirm(json_body, *, otp_id)[source]

Verify the OTP code.

Verifies the code sent to the user’s email. If exactly one active user matches, returns a login response with an access token and consumes the session. If multiple users match, returns {“type”: “select”} — use otp_login.list and otp_login.select to choose. If no users match, returns 404 (same as wrong code, anti-enumeration). Allows up to 5 attempts before the session is locked.

Parameters:
Returns:

Either a LoginResponse or a selection marker.

Return type:

OTPLoginSingleResponse | OTPLoginMultiResponse

create(json_body)[source]

Create an OTP login session and send a code to the given email.

First step of the OTP login flow. After creating, call otp_login.confirm with the code from the email. For single-user matches that returns a login response directly. For multi-user matches, use otp_login.list and otp_login.select.

The session is bound to the creating client’s IP. A valid proof-of-work solution is required to prevent automated abuse. Always returns success regardless of whether matching users exist (anti-enumeration).

Parameters:

json_body (CreateOTPLoginData) – The body of the request. See CreateOTPLoginData for information about the possible fields. You can provide this data as a CreateOTPLoginData or as a dictionary.

Returns:

An OTP session identifier.

Return type:

OTPLoginResponse

list(*, otp_id, page_size=20, cg_otp_login_code)[source]

List users matching this OTP session (paginated).

Only available after otp_login.confirm returned {“type”: “select”}. Requires the OTP code in the Cg-Otp-Login-Code header for authentication. Does not consume the session — can be called repeatedly until the session expires.

Each user includes a can_login flag indicating whether they are allowed to log in directly (users managed by an external system like LTI/SSO may not be).

Parameters:

  • otp_id (str) – The OTP session identifier.

  • page_size (int) – The size of a single page, maximum is 50.

  • cg_otp_login_code (str)

Returns:

Paginated list of matching users.

Return type:

Response[OTPLoginableUser]

select(json_body, *, otp_id)[source]

Select a user from the multi-user list and log in.

Only available after otp_login.confirm returned {“type”: “select”}. Requires the OTP code for re-authentication. Consumes the session — a second call will return 404.

Parameters:
Returns:

A login response for the selected user.

Return type:

OTPLoginSingleResponse