Initiate Login

post/auth/login-init

Initiate the login sequence for an existing user. Multiple authentication methods are supported. To initiate login for a new user, use Sign Up. Alternatively, if you'd like to use login-init for both new and existing users, use the autoSignup request body option. To complete the login flow, use Complete Login. For more details, see Authentication.

Request

Body application/json

One of

loginMethodstringrequired
Allowed values:algorand
The login method to use.
networkstringrequired
Allowed values:algorand-mainnetalgorand-testnet
The blockchain network associated with the web3 address.
clientApplicationIdstringrequired
ID of the client application created in an Immersve partner profile.
scopesstring[]required
An array of authorization scopes requested by the client application.
addressstringrequired
The web3 address to which the challenge is directed.
autoSignupboolean
Allowed values:truefalse
If set to true, creates a user account if one does not already exist for the web3 address attempting to log in.

loginMethodstringrequired
Allowed values:siwe
The login method to use.
networkstringrequired
Allowed values:polygon-mainnetpolygon-amoyarbitrum-mainnetarbitrum-sepoliabase-mainnetbase-sepoliasei-mainnetsei-testnetmonad-mainnetmonad-testnet
The blockchain network associated with the web3 address.
For more information on supported networks, see Supported Chains.
clientApplicationIdstringrequired
ID of the client application created in an Immersve partner profile.
scopesstring[]required
An array of authorization scopes requested by the client application.
addressstringrequired
The web3 address to which the challenge is directed.
urlstring<uri>required
Domain in the <domain> wants you to sign in.. of the EIP-4361 is derived from the host fragment of this parameter. The client application identified by clientApplicationId must allow this URL.
autoSignupboolean
Allowed values:truefalse
If set to true, creates a user account if one does not already exist for the web3 address attempting to log in.

loginMethodstringrequired
Allowed values:xrpl
The login method to use.
networkstringrequired
Allowed values:xahau-mainnetxahau-testnet
The blockchain network associated with the web3 address.
clientApplicationIdstringrequired
ID of the client application created in an Immersve partner profile.
scopesstring[]required
An array of authorization scopes requested by the client application.
publicKeystringrequired
The public key of the web3 address to which the challenge is directed.
autoSignupboolean
Allowed values:truefalse
If set to true, creates a user account if one does not already exist for the web3 address attempting to log in.

Response

Successful operation.

Body application/json

idstring
The unique identifier of the login request.
loginMethodstring
The login method used.
modestring
Allowed values:cardholder-login
Identifies intention of the user.
networkstring
The blockchain network associated with the web3 address.
clientApplicationIdstring
ID of the client application created in an Immersve partner profile.
scopesstring[]
An array of authorization scopes requested by the client application.
createdAtstring
The date and time the login request was created.
urlstring<uri>
Domain in the <domain> wants you to sign in.. of the EIP-4361 is derived from the host fragment of this parameter. The client application identified by clientApplicationId must allow this URL.
addressstring
The web3 address to which the challenge is directed.
signingChallengeobject
- descriptionstring
  The description of the challenge.
- createdAtstring
  The date and time the challenge was created.
- expiresAtstring
  The date and time the challenge expires.
- messagestring
  The message to be signed by the web3 address owner.

CLIENT_APPLICATION_DOMAIN_NOT_ALLOWED Client application domain not allowed.

ACCOUNT_DOES_NOT_EXIST Unable to log in. Account does not exist.

Body application/json

statusCodeintegerrequired
statusNamestringrequired
errorCodestringrequired
reasonstring

Example

Example Request

Server

curl https://api.immersve.com/auth/login-init \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "loginMethod": "algorand",
  "network": "algorand-mainnet",
  "clientApplicationId": "29097f50d221858223a17633e36716f9",
  "scopes": [
    "cardholder-partner"
  ],
  "address": "EY434UKQU4EX2M63RXFIKZUUKZG4GY5GWV..",
  "autoSignup": true
}'

curl https://api.immersve.com/auth/login-init \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "loginMethod": "siwe",
  "network": "polygon-mainnet",
  "clientApplicationId": "29097f50d221858223a17633e36716f9",
  "scopes": [
    "cardholder-partner"
  ],
  "address": "0xA3058369d6A481B1ff08F62B352409c3D709De9b",
  "url": "https://app.immersve.com",
  "autoSignup": true
}'

curl https://api.immersve.com/auth/login-init \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "loginMethod": "xrpl",
  "network": "xahau-mainnet",
  "clientApplicationId": "29097f50d221858223a17633e36716f9",
  "scopes": [
    "cardholder-partner"
  ],
  "publicKey": "EDA2F521129EC961DABA759DA..",
  "autoSignup": true
}'

curl https://test.immersve.com/auth/login-init \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "loginMethod": "algorand",
  "network": "algorand-mainnet",
  "clientApplicationId": "29097f50d221858223a17633e36716f9",
  "scopes": [
    "cardholder-partner"
  ],
  "address": "EY434UKQU4EX2M63RXFIKZUUKZG4GY5GWV..",
  "autoSignup": true
}'

curl https://test.immersve.com/auth/login-init \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "loginMethod": "siwe",
  "network": "polygon-mainnet",
  "clientApplicationId": "29097f50d221858223a17633e36716f9",
  "scopes": [
    "cardholder-partner"
  ],
  "address": "0xA3058369d6A481B1ff08F62B352409c3D709De9b",
  "url": "https://app.immersve.com",
  "autoSignup": true
}'

curl https://test.immersve.com/auth/login-init \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "loginMethod": "xrpl",
  "network": "xahau-mainnet",
  "clientApplicationId": "29097f50d221858223a17633e36716f9",
  "scopes": [
    "cardholder-partner"
  ],
  "publicKey": "EDA2F521129EC961DABA759DA..",
  "autoSignup": true
}'

Example Response

{
  "id": "49ae8f3a3928491",
  "loginMethod": "algorand",
  "mode": "cardholder-login",
  "network": "algorand-mainnet",
  "clientApplicationId": "29097f50d221858223a17633e36716f9",
  "scopes": [
    "cardholder-partner"
  ],
  "createdAt": "2024-02-26T08:24:11.047Z",
  "url": "https://app.immersve.com",
  "address": "0x4d6c3443...",
  "signingChallenge": {
    "description": "Immersve wants to ...",
    "createdAt": "2024-02-26T08:24:11.047Z",
    "expiresAt": "2024-03-20T08:20:00Z",
    "message": "Immersve wants to ..."
  }
}

{
  "statusCode": 403,
  "statusName": "Forbidden",
  "errorCode": "FORBIDDEN",
  "reason": "Unauthorized"
}