General Read

pixiCheckPixiUserLogin

Checks a Pixi user name and password, optionally a permission code, and returns whether the login is valid together with the user's e-mail and real name.

Validates the credentials of a Pixi user (table UCS_USERS).

The password is passed through dbo.PixiEncrypt. The stored password USER_PWD is compared with this encrypted value.
The user is looked up by UserName. If the user's USER_PWD is NULL, the procedure uses version 2 password validation and calls pixi.UserPassword_ValidateV2 with user name and plain password. If that procedure reports success, the password check counts as passed.
ValidUser is 1 only if a user with the given UserName exists and all of these conditions are met:
- the password matches, either by the classic comparison or by the V2 validation;
- if CheckPermission is set, the user has a role (USER_HAS_ROLES → USER_ROLES → ROLE_HAS_PERMISSIONS) that grants a permission whose Permission_Code equals CheckPermission. An empty string counts as "no permission check";
- the account has not expired: User_expire is not 1, or it is 1 and Expiration_date is later than the current time;
- User_active = 1. Otherwise ValidUser is 0.
If the login is valid, the output parameters UserEmail and UserRealName are filled from User_Email and REAL_NAME. NULL values become empty strings.
Unless SuppressDataset = 1, the procedure returns one row with ValidUser, UserName, UserEmail and UserRealName.

Notes

The returned row contains UserEmail and UserRealName whenever the user name exists, even if ValidUser is 0, for example after a wrong password. If the user does not exist, both columns are NULL. The output parameters UserEmail/UserRealName, by contrast, are set only on a valid login.
dbo.PixiEncrypt is only a simple XOR obfuscation, not a cryptographic hash. Send the password only over the encrypted connection.
pixi.UserPassword_ValidateV2 is not attached. Its exact logic and any side effects, such as logging or lockout, are unknown.
If User_expire is NULL, the expiry condition does not evaluate to true, so such users are rejected.
The comparison of the user name depends on the database collation. The initial V2 lookup uses COLLATE DATABASE_DEFAULT, the validity check does not.
All reads in the validity check use NOLOCK.

Parameters

Parameter	Type	Default	Description
`UserName` Required	varchar(1024) string	–	Pixi user name (`UCS_USERS.USER_NAME`). Example: `shopapi`
`Password` Required	varchar(1024) string	–	Plain-text password of the user. Example: `S3cret!2024`
`CheckPermission`	varchar(5) string	NULL	Optional permission code (`User_Permissions.Permission_Code`) that the user must have through one of the roles. `NULL` or an empty string skips the permission check. Example: `API`
`ValidUser` OUTPUT	bit boolean	NULL	Output: `1` if the login is valid, otherwise `0`.
`SuppressDataset`	bit boolean	NULL	If `1`, no result set is returned and only the output parameters are set. `NULL` is treated as `0`. Allowed values `0` – Return the result row (default). `1` – Suppress the result row. Example: `0`
`UserEmail` OUTPUT	varchar(100) string	NULL	Output: the user's e-mail address, set only if the login is valid. An empty string if none is stored.
`UserRealName` OUTPUT	varchar(40) string	NULL	Output: the user's real name, set only if the login is valid. An empty string if none is stored.

Response

Result set 1 · If `SuppressDataset` is not `1`.

One row with the result of the login check.

Column	Type	Description
`ValidUser`	bit boolean	`1` if the login is valid, otherwise `0`.
`UserName`	varchar(1024) string	The user name as passed in.
`UserEmail` Nullable	string	E-mail address from `UCS_USERS.User_Email`, or an empty string. Filled whenever the user exists, even if the login is invalid. `NULL` if the user does not exist.
`UserRealName` Nullable	string	Real name from `UCS_USERS.REAL_NAME`, or an empty string. Filled whenever the user exists, even if the login is invalid. `NULL` if the user does not exist.

Response example

<SqlRowSet1>
  <row>
    <ValidUser>true</ValidUser>
    <UserName>shopapi</UserName>
    <UserEmail>shopapi@example.com</UserEmail>
    <UserRealName>Shop Schnittstelle</UserRealName>
  </row>
</SqlRowSet1>

Examples

POST https://apigateway.descartes.com/tms/pixi/
Content-Type: text/xml; charset=utf-8
Authorization: Basic BASE64(USERNAME:PASSWORD)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiCheckPixiUserLogin>
      <UserName>shopapi</UserName>
      <Password>S3cret!2024</Password>
      <!-- <CheckPermission>API</CheckPermission> -->
      <!-- <ValidUser>?</ValidUser> -->
      <!-- <SuppressDataset>0</SuppressDataset> -->
      <!-- <UserEmail>?</UserEmail> -->
      <!-- <UserRealName>?</UserRealName> -->
    </ns1:pixiCheckPixiUserLogin>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

curl -X POST 'https://apigateway.descartes.com/tms/pixi/' \
  --user 'USERNAME:PASSWORD' \
  --header 'Content-Type: text/xml; charset=utf-8' \
  --data-binary @- <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiCheckPixiUserLogin>
      <UserName>shopapi</UserName>
      <Password>S3cret!2024</Password>
      <!-- <CheckPermission>API</CheckPermission> -->
      <!-- <ValidUser>?</ValidUser> -->
      <!-- <SuppressDataset>0</SuppressDataset> -->
      <!-- <UserEmail>?</UserEmail> -->
      <!-- <UserRealName>?</UserRealName> -->
    </ns1:pixiCheckPixiUserLogin>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML

<?php

$soapClient = new SoapClient(null, [
    'login' => 'USERNAME',
    'password' => 'PASSWORD',
    'location' => 'https://apigateway.descartes.com/tms/pixi/',
    'uri' => 'https://apigateway.descartes.com/tms/pixi/',
]);

$arguments = [
    'UserName' => 'shopapi',
    'Password' => 'S3cret!2024',
    // 'CheckPermission' => 'API',
    // 'ValidUser' => '?',
    // 'SuppressDataset' => '0',
    // 'UserEmail' => '?',
    // 'UserRealName' => '?',
];

$soapArguments = [];
foreach ($arguments as $name => $value) {
    $soapArguments[] = new SoapVar($value, XSD_STRING, '', '', $name);
}

$response = $soapClient->__soapCall('pixiCheckPixiUserLogin', $soapArguments);

Tables used

UCS_USERS · Read USER_HAS_ROLES · Read USER_ROLES · Read ROLE_HAS_PERMISSIONS · Read User_Permissions · Read

SQL object:: dbo.pipiCheckPixiUserLogin