Administrative logon/logoff (SOAP API)

  • Published on Jan 22, 2026
  • 4 minute(s) read
Prev Next

Each SOAP administration operation performed by an administrative user requires a successful administrative logon. OneSpan Authentication Server provides a session identifier (sessionID) as a response to a successful administrative logon request. Each administrative operation of OneSpan Authentication Server requires that session identifier and must be performed from the same client location.

To support logon/logoff operations via the SOAP API, a SOAP client record in OneSpan Authentication Server with the Administration Logon client type is required for the computer where your SOAP client application is running.

To log on/log off via the SOAP API

  1. Create a SOAP request.

  2. Specify the logon or logoff SOAP operation in the SOAP request.

  3. Specify one or more credential attributes as parameters for the SOAP operation. Attributes are key/value pairs.

  4. Import the OneSpan Authentication Server SSL server certificate as trusted root certificate on the machine where your client application is running.

    This will allow your SOAP client application to connect to OneSpan Authentication Server securely via SSL.

  5. Send the SOAP request to OneSpan Authentication Server. By default, the SOAP request should be transmitted over HTTPS with the OneSpan Authentication Server.

    By default, OneSpan Authentication Server is configured to accept SOAP requests on port 8888.

  6. Receive the SOAP response.

  7. Process the SOAP response.

For more information about the structure of SOAP messages, see SOAP message structure.

SOAP request structure

logon and logoff SOAP requests have the same format. A logon SOAP request typically use the following format:

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:adm="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Administration">
    <soapenv:Header/>
    <soapenv:Body>
        <adm:logon>
            <attributeSet>
                <!--Zero or more repetitions:-->
                <attributes>
                    <value xsi:type="xsd:!!!!!!">?????</value>
                    <attributeID>?????</attributeID>
                </attributes>
            </attributeSet>
        </adm:logon>
    </soapenv:Body>
</soapenv:Envelope>

The SOAP body element should only contain a logon or logoff element (line 8). This element is defined in the namespace adm. Therefore, adm needs to be declared in the Envelope element as an attribute.

A valid logon or logoff request needs to follow these additional rules:

  • The logon or logoff element should contain only one AttributeSet element.

  • The AttributeSet element should contain zero or more provisioning attribute elements.

Each attribute element should contain the following sub-elements:

  • attributeID (required). The attribute identifier. The supported credential attribute identifiers are listed in SOAP authentication (Overview).

  • value (required). The attribute value. This element also requires the specification of the value type using the following attribute definition xsi=type=”xsd:type.

  • attributeOptions (optional). This element provides directive information about how OneSpan Authentication Server should handle the attribute value during request processing. Following options are supported for this element:

    • NULL. Indicates that the specified attribute should be set to zero.

    • NEGATIVE. Used for search criteria to say NO when searching for a specific attribute.

    • MASKED. Used to indicate OneSpan Authentication Server to mask the attribute value (e.g. when auditing the SOAP request).

To set an attribute option, add the option element in the attributeOptions element and give the option element the value true.

To set the MASKED option, add the following:

<attributeOptions><masked>true</masked></attributeOptions>

SOAP response structure

logon and logoff SOAP responses have the same format. A logon SOAP response typically use the following format:

<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:adm="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Administration">
    <!-- ... Additional namespace declarations -->
    <soapenv:Header/>
    <soapenv:Body>
        <adm:logonResponse>
            <results xsi:type="CREDENTIAL-TYPES:CredentialResults">
                <resultCodes xsi:type="BASIC-TYPES:ResultCodes">
                    <returnCodeEnum>RET_SUCCESS</returnCodeEnum>
                    <statusCodeEnum>STAT_SUCCESS</statusCodeEnum>
                    <returnCode>0</returnCode>
                    <statusCode>0</statusCode>
                </resultCodes>
                <resultAttribute xsi:type="CREDENTIAL-TYPES:CredentialAttributeSet">
                    <!--Zero or more repetitions:-->
                    <attributes>
                        <value xsi:type="xsd:!!!!!!">?????</value>
                        <attributeID>?????</attributeID>
                    </attributes>
                </resultAttribute>
                <errorStack xsi:type="BASIC-TYPES:ErrorStack"/>
            </results>
        </adm:logonResponse>
    </soapenv:Body>
</soapenv:Envelope>

The SOAP body element should only contain a logonResponse element (line 9). The logonResponse element always contains a results element, which in turn contains the following elements:

  • resultCodes (required). This element contains the following sub-elements:

    • returnCode. The operation return code indicating the overall result of the request processing.

    • statusCode. The operation status code indicating the reason for failure of any returnCode different from success (0).

    • returnCodeEnum. The identifier corresponding to the returnCode.

    • statusCodeEnum. The identifier corresponding to the statusCode.

  • resultAttribute (required). This element contains zero or more attributes elements.

  • errorStack (required). Contains zero or more errors elements.

    • errors. Each errors element contains the following sub-elements:

      • errorCode. The error code integer.

      • errorDesc. A string representation of the error code.

For a complete list of possible error codes, see Error codes and messages.

In this case, the resultattribute element is used to refer to credential attribute elements.