Authentication

The following section documents everything related to authentication.

PartialAccount

Attributes
class stoat.PartialAccount(*, id, email)[source]

Represents a partial Stoat account.

id

The unique account ID.

Type:

str

email

The email associated with this account.

Type:

str

MFATicket

Attributes
class stoat.MFATicket(*, id, account_id, token, validated, authorized, last_totp_code)[source]

The MFA ticket.

id

The unique ticket ID.

Type:

str

account_id

The associated account ID.

Type:

str

token

The unique token.

Type:

str

validated

Whether this ticket has been validated (can be used for account actions).

Type:

bool

authorized

Whether this ticket is authorized (can be used to log an user in).

Type:

bool

last_totp_code

The TOTP code at time of ticket creation.

Type:

Optional[str]

WebPushSubscription

Attributes
class stoat.WebPushSubscription(*, endpoint, p256dh, auth)[source]

Represents WebPush subscription.

endpoint

The HTTP endpoint associated with push subscription.

Type:

str

p256dh

The Elliptic curve Diffie–Hellman public key on the P-256 curve.

Type:

str

auth

The authentication secret.

Type:

str

PartialSession

Attributes
Methods
class stoat.PartialSession(*, state, id, name)[source]

Represents a partial Stoat authentication session.

This inherits from Base.

name

The user-friendly client name.

Type:

str

await edit(*, http_overrides=None, friendly_name=UNDEFINED)[source]

This function is a coroutine.

Edits the session.

Parameters:

friendly_name (UndefinedOr[str]) – The new user-friendly client name.

Raises:

  • Unauthorized – Possible values for type:

    Value

    Reason

    InvalidSession

    One of these:

    • The current user token is invalid.

    • The session you tried to edit didn’t belong to your account.

  • NotFound – Possible values for type:

    Value

    Reason

    UnknownUser

    The session was not found.

  • InternalServerError – Possible values for type:

    Value

    Reason

    Populated attributes

    DatabaseError

    Something went wrong during querying database.

    operation, with_
Returns:

The newly updated session.

Return type:

PartialSession

await revoke(*, http_overrides=None)[source]

This function is a coroutine.

Deletes the session.

Fires SessionDeleteEvent for the provided session.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

  • Unauthorized – Possible values for type:

    Value

    Reason

    InvalidSession

    The current user token is invalid.

    InvalidToken

    The provided session did not belong to your account.

  • NotFound – Possible values for type:

    Value

    Reason

    UnknownUser

    The provided session was not found.

  • InternalServerError – Possible values for type:

    Value

    Reason

    Populated attributes

    DatabaseError

    Something went wrong during querying database.

    operation, with_

Session

Attributes
class stoat.Session(*, state, id, name, user_id, token, internal_last_seen, origin, subscription)[source]

Represents a Stoat authentication session.

This inherits from PartialSession.

user_id

The ID of associated user.

Type:

str

token

The session token.

Type:

str

internal_last_seen

When the session was seen last time. If None, defaults to created_at.

Added in version 1.2.

Type:

Optional[datetime]

origin

The session’s origin.

Added in version 1.2.

Type:

Optional[str]

subscription

The Web Push subscription associated with this session.

Type:

Optional[WebPushSubscription]

property last_seen[source]

When the session was seen last time.

Added in version 1.2.

Type:

class

Type:

~datetime.datetime

MFARequired

Attributes
Methods
class stoat.MFARequired(*, ticket, allowed_methods, state, friendly_name)[source]

The password is valid, but MFA is required.

ticket

The MFA ticket.

Type:

str

allowed_methods

The allowed methods.

Type:

List[MFAMethod]

await use_recovery_code(code, *, http_overrides=None, friendly_name=UNDEFINED)[source]

This function is a coroutine.

Complete MFA login flow.

Parameters:

  • code (str) – The valid recovery code.

  • http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

  • friendly_name (UndefinedOr[Optional[str]]) – The user-friendly client name. If set to UNDEFINED, this defaults to friendly_name.

Raises:

  • HTTPException – Possible values for type:

    Value

    Reason

    DisallowedMFAMethod

    You tried to use disallowed MFA verification method.

  • Unauthorized – Possible values for type:

    Value

    Reason

    InvalidToken

    The provided recovery code is invalid.

  • Forbidden – Possible values for type:

    Value

    Reason

    LockedOut

    The account was locked out.

    UnverifiedAccount

    The account you tried to log into is currently unverified.

  • InternalServerError – Possible values for type:

    Value

    Reason

    Populated attributes

    DatabaseError

    Something went wrong during querying database.

    operation, with_
Returns:

The session if successfully logged in, or AccountDisabled containing user ID associated with the account.

Return type:

Union[Session, AccountDisabled]

await use_totp(code, *, http_overrides=None, friendly_name=UNDEFINED)[source]

This function is a coroutine.

Complete MFA login flow.

Parameters:

  • code (str) – The valid TOTP code.

  • http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

  • friendly_name (UndefinedOr[Optional[str]]) – The user-friendly client name. If set to UNDEFINED, this defaults to friendly_name.

Raises:

  • HTTPException – Possible values for type:

    Value

    Reason

    DisallowedMFAMethod

    You tried to use disallowed MFA verification method.

  • Unauthorized – Possible values for type:

    Value

    Reason

    InvalidToken

    The provided TOTP code is invalid.

  • Forbidden – Possible values for type:

    Value

    Reason

    LockedOut

    The account was locked out.

    UnverifiedAccount

    The account you tried to log into is currently unverified.

  • InternalServerError – Possible values for type:

    Value

    Reason

    Populated attributes

    DatabaseError

    Something went wrong during querying database.

    operation, with_
Returns:

The session if successfully logged in, or AccountDisabled containing user ID associated with the account.

Return type:

Union[Session, AccountDisabled]

AccountDisabled

Attributes
class stoat.AccountDisabled(*, user_id)[source]

The password/MFA are valid, but account is disabled.

user_id

The ID of the disabled user account.

Type:

str

MFAStatus

Attributes
class stoat.MFAStatus(*, totp_mfa, recovery_active)[source]
totp_mfa

Whether the account has MFA TOTP enabled.

Type:

bool

recovery_active

Whether the account has recovery codes.

Type:

bool

BaseMFAResponse

class stoat.BaseMFAResponse[source]

Represents a MFA verification way.

ByPassword

Attributes
class stoat.ByPassword(password)[source]

Represents MFA verification by password.

This inherits from BaseMFAResponse.

password

The password.

Type:

str

ByRecoveryCode

Attributes
class stoat.ByRecoveryCode(code, /)[source]

Represents MFA verification by recovery code.

This inherits from BaseMFAResponse.

code

The recovery code.

Type:

str

ByTOTP

Attributes
class stoat.ByTOTP(code, /)[source]

Represents MFA verification by TOTP code.

This inherits from BaseMFAResponse.

code

The TOTP code.

Type:

str

MFAResponse

class stoat.MFAResponse

An union of all possible MFA verification responses.

The following classes are included in this union:

LoginResult

class stoat.LoginResult

An union of all login responses.

The following classes are included in this union: