Skip to main content

Create a new session​

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 object required

    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 string required

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

    userVerificationRequirement string required

    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."

    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
    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
POST /v2beta/sessions

Authorization

name: OAuth2type: oauth2scopes: openid,urn:zitadel:iam:org:project:id:zitadel:audflows: {
  "authorizationCode": {
    "authorizationUrl": "$CUSTOM-DOMAIN/oauth/v2/authorize",
    "tokenUrl": "$CUSTOM-DOMAIN/oauth/v2/token",
    "scopes": {
      "openid": "openid",
      "urn:zitadel:iam:org:project:id:zitadel:aud": "urn:zitadel:iam:org:project:id:zitadel:aud"
    }
  }
}

Request

Base URL
https://$CUSTOM-DOMAIN
Bearer Token
Content-Type
Body required
{

  "checks": {

    "user": {

      "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",

      "loginName": "mini@mouse.com"

    },

    "password": {

      "password": "V3ryS3cure!"

    },

    "webAuthN": {

      "credentialAssertionData": {}

    },

    "idpIntent": {

      "idpIntentId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",

      "idpIntentToken": "SJKL3ioIDpo342ioqw98fjp3sdf32wahb="

    },

    "totp": {

      "code": "323764"

    },

    "otpSms": {

      "code": "3237642"

    },

    "otpEmail": {

      "code": "3237642"

    }

  },

  "metadata": {},

  "challenges": {

    "webAuthN": {

      "domain": "string",

      "userVerificationRequirement": "USER_VERIFICATION_REQUIREMENT_UNSPECIFIED"

    },

    "otpSms": {

      "returnCode": true

    },

    "otpEmail": {

      "sendCode": {

        "urlTemplate": "https://example.com/otp/verify?userID={{.UserID}}&code={{.Code}}"

      },

      "returnCode": {}

    }

  },

  "userAgent": {

    "fingerprintId": "string",

    "ip": "string",

    "description": "string",

    "header": {}

  },

  "lifetime": "18000s"

}
Accept
curl / cURL
curl -L -X POST 'https://$CUSTOM-DOMAIN/v2beta/sessions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "checks": {
    "user": {
      "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
      "loginName": "mini@mouse.com"
    },
    "password": {
      "password": "V3ryS3cure!"
    },
    "webAuthN": {
      "credentialAssertionData": {}
    },
    "idpIntent": {
      "idpIntentId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
      "idpIntentToken": "SJKL3ioIDpo342ioqw98fjp3sdf32wahb="
    },
    "totp": {
      "code": "323764"
    },
    "otpSms": {
      "code": "3237642"
    },
    "otpEmail": {
      "code": "3237642"
    }
  },
  "metadata": {},
  "challenges": {
    "webAuthN": {
      "domain": "string",
      "userVerificationRequirement": "USER_VERIFICATION_REQUIREMENT_UNSPECIFIED"
    },
    "otpSms": {
      "returnCode": true
    },
    "otpEmail": {
      "sendCode": {
        "urlTemplate": "https://example.com/otp/verify?userID={{.UserID}}&code={{.Code}}"
      },
      "returnCode": {}
    }
  },
  "userAgent": {
    "fingerprintId": "string",
    "ip": "string",
    "description": "string",
    "header": {}
  },
  "lifetime": "18000s"
}'