Skip to main content

Create a new session

POST 
/v2/sessions

Create a new session. A token will be returned, which is required for further updates of the session.

Request​

Body

required

    checks

    object

    "Check for user and password. Successful checks will be stated as factors on the session."

    user

    object

    "checks the user and updates the session on success"

    userId string

    Possible values: non-empty and <= 200 characters

    loginName string

    Possible values: non-empty and <= 200 characters

    password

    object

    "Checks the password and updates the session on success. Requires that the user is already checked, either in the previous or the same request."

    password string

    Possible values: non-empty and <= 200 characters

    webAuthN

    object

    "Checks the public key credential issued by the WebAuthN client. Requires that the user is already checked and a WebAuthN challenge to be requested, in any previous request."

    credentialAssertionData objectrequired

    Possible values: >= 55 characters and <= 1048576 characters

    JSON representation of public key credential issued by the webAuthN client

    idpIntent

    object

    "Checks the IDP intent. Requires that the userlink is already checked and a successful idp intent."

    idpIntentId string

    Possible values: non-empty and <= 200 characters

    ID of the idp intent, previously returned on the success response of the IDP callback

    idpIntentToken string

    Possible values: non-empty and <= 200 characters

    token of the idp intent, previously returned on the success response of the IDP callback

    totp

    object

    "Checks the Time-based One-Time Password and updates the session on success. Requires that the user is already checked, either in the previous or the same request."

    code string

    Possible values: >= 6 characters and <= 6 characters

    otpSms

    object

    "Checks the One-Time Password sent over SMS and updates the session on success. Requires that the user is already checked, either in the previous or the same request."

    code string

    Possible values: non-empty

    otpEmail

    object

    "Checks the One-Time Password sent over Email and updates the session on success. Requires that the user is already checked, either in the previous or the same request."

    code string

    Possible values: non-empty

    metadata

    object

    "custom key value list to be stored on the session"

    property name* byte

    challenges

    object

    webAuthN

    object

    domain stringrequired

    "Domain on which the session was created. Will be used in the WebAuthN challenge."

    userVerificationRequirement stringrequired

    Possible values: [USER_VERIFICATION_REQUIREMENT_UNSPECIFIED, USER_VERIFICATION_REQUIREMENT_REQUIRED, USER_VERIFICATION_REQUIREMENT_PREFERRED, USER_VERIFICATION_REQUIREMENT_DISCOURAGED]

    Default value: USER_VERIFICATION_REQUIREMENT_UNSPECIFIED

    "User verification that is required during validation. When set to USER_VERIFICATION_REQUIREMENT_REQUIRED the behaviour is for passkey authentication. Other values will mean U2F"

    otpSms

    object

    returnCode boolean

    otpEmail

    object

    sendCode

    object

    urlTemplate string

    Possible values: non-empty and <= 200 characters

    Optionally set a url_template, which will be used in the mail sent by ZITADEL to guide the user to your verification page. If no template is set, the default ZITADEL url will be used.

    The following placeholders can be used: Code, UserID, LoginName, DisplayName, PreferredLanguage, SessionID

    returnCode object

    userAgent

    object

    fingerprintId string
    ip string
    description string

    header

    object

    property name*

    object

    A header may have multiple values. In Go, headers are defined as map[string][]string, but protobuf doesn't allow this scheme.

    values string[]
    lifetime string

    "duration (in seconds) after which the session will be automatically invalidated"

Responses​

OK

Schema

    details

    object

    sequence uint64

    on read: the sequence of the last event reduced by the projection

    on manipulation: the timestamp of the event(s) added by the manipulation

    changeDate date-time

    on read: the timestamp of the last event reduced by the projection

    on manipulation: the timestamp of the event(s) added by the manipulation

    resourceOwner resource_owner is the organization or instance_id an object belongs to (string)
    sessionId string

    "id of the session"

    sessionToken string

    "The current token of the session, which is required for delete session, get session or the request of other resources."

    challenges

    object

    webAuthN

    object

    publicKeyCredentialRequestOptions object

    Options for Assertion Generaration (dictionary PublicKeyCredentialRequestOptions). Generated helper methods transform the field to JSON, for use in a WebauthN client. See also: https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialrequestoptions

    otpSms string
    otpEmail string
Loading...