=============
API Reference
=============

The Swivel Secure API (often referred to as Agent-XML) is an XML-based interface used for integrating the AuthControl Sentry server with other applications. It allows external applications to perform authentication, manage users, and retrieve reports.

Overview
========

The API is divided into four functional subsets:

1.  **Authentication API:** Used for user login, session management, and credential requests.
2.  **Admin API:** Used for creating, updating, and deleting users within specific repositories.
3.  **Helpdesk API:** Used for user support tasks like unlocking accounts, resetting PINs, and sending security strings.
4.  **Reporting API:** Used for retrieving lists of users based on status (idle, disabled, locked) or retrieving user counts.

Communication Protocols
-----------------------

* **Method:** HTTP POST.
* **Format:** XML Request and XML Response.
* **Case Sensitivity:** The API is case-sensitive.
* **Ports:** Typically ``8080`` (HTTP) or ``443`` (HTTPS/Proxy), depending on appliance configuration.
* **Contexts:**
    * Authentication requests go to: ``/sentry/AgentXML`` (or ``/pinsafe/AgentXML``).
    * Admin, Helpdesk, and Reporting requests go to: ``/sentry/AdminXML`` (or ``/pinsafe/AdminXML``).

**Security**
All requests require a **Shared Secret** configured on the Swivel server under **Server -> Agents**. The IP address of the requesting machine must also match the Agent configuration.

------------------------------

Authentication API
==================

The Authentication API is used by agents (VPNs, Web Portals, Custom Apps) to authenticate users.

**Endpoint:** ``/sentry/AgentXML``
**Root Element:** ``<SASRequest>``

Standard Login Request
----------------------

This request is used for both Single Channel and Dual Channel logins.

.. code-block:: xml

    <?xml version="1.0" ?>
    <SASRequest>
        <Version>3.6</Version>
        <Secret>shared_secret</Secret>
        <Action>login</Action>
        <Username>some_user</Username>
        <Password>password</Password>
        <OTC>1234</OTC>
    </SASRequest>

**Response:**

.. code-block:: xml

    <?xml version="1.0" ?>
    <SASResponse>
        <Version>3.6</Version>
        <Result>PASS</Result>
    </SASResponse>

Authentication By Attribute
---------------------------

Allows authentication using an attribute (e.g., email) instead of the username.

.. code-block:: xml

    <SASRequest>
        <Version>3.6</Version>
        <Secret>shared_secret</Secret>
        <Action>login</Action>
        <Username>some_user@domain.com</Username>
        <Attribute>email</Attribute>
        <Password>password</Password>
        <OTC>1234</OTC>
    </SASRequest>

Check Password
--------------

Checks a user's password without performing a full authentication or logging a failure. This verifies either the Swivel password or Repository password depending on policy.

.. code-block:: xml

    <SASRequest>
        <Version>3.6</Version>
        <Secret>shared_secret</Secret>
        <Action>checkpassword</Action>
        <Username>some_user</Username>
        <Password>password</Password>
    </SASRequest>

Starting a Session
------------------

For session-based authentication (e.g., TURing image), the agent must start a session to receive a Session ID.

.. code-block:: xml

    <SASRequest>
        <Version>3.6</Version>
        <Secret>shared_secret</Secret>
        <Action>sessionstart</Action>
        <Username>some_user</Username>
    </SASRequest>

**Response:**

.. code-block:: xml

    <SASResponse>
        <Version>3.6</Version>
        <Result>PASS</Result>
        <SessionID>c7379ef1b41f90a4900548a75e13f62a</SessionID>
    </SASResponse>

Change PIN
----------

Allows a user to change their PIN. Requires the existing password, existing OTC, and a new OTC representing the new PIN.

.. code-block:: xml

    <SASRequest>
        <Version>3.6</Version>
        <Secret>shared_secret</Secret>
        <Action>changepin</Action>
        <Username>some_user</Username>
        <Password>password</Password>
        <NewPassword>newpassword</NewPassword>
        <OTC>1234</OTC>
        <NewOTC>4321</NewOTC>
    </SASRequest>

Mobile Client Provisioning
--------------------------

**Step 1: Request Provision Code**
Requests a provision code be sent to the user (usually via SMS).

.. code-block:: xml

    <SASRequest>
        <Version>3.6</Version>
        <Action>provisioncode</Action>
        <Username>some_user</Username>
    </SASRequest>

**Step 2: Submit Provision Code**
The client submits the code to receive a unique Client ID.

.. code-block:: xml

    <SASRequest>
        <Version>3.6</Version>
        <Action>provision</Action>
        <ProvisionCode>code</ProvisionCode>
        <Username>username</Username>
    </SASRequest>

Ping
----

Tests that the Swivel application is available.

.. code-block:: xml

    <SASRequest>
        <Version>3.6</Version>
        <Action>ping</Action>
    </SASRequest>

User Exists Check
-----------------

Verifies if a user exists in the database before attempting authentication.

.. code-block:: xml

    <SASRequest>
        <Version>3.6</Version>
        <Secret>shared_secret</Secret>
        <Action>exists</Action>
        <Username>some_user</Username>
    </SASRequest>

------------------------------

Admin API
=========

The Admin API allows for the management of user accounts, including creating, deleting, and updating users.

**Endpoint:** ``/sentry/AdminXML``
**Root Element:** ``<AdminRequest>``

**Important:** Users created or managed via the Admin API are assigned to a repository named after the **Agent**. To use these commands, the Agent must have the option **"Act as Repository"** enabled in the Swivel Administration Console. If you need to manage a standard repository (like AD), you must define an Agent with the exact same name as the Repository.

Create User
-----------

Creates a new user with defined groups, policies, and attributes.

.. code-block:: xml

    <?xml version="1.0" ?>
    <AdminRequest secret="MyAdminAgent" version="3.4">
        <Create>
            <User name="bob">
                <Credentials pin="1234"/>
                <Groups>
                    <Group name="EmailUsers"/>
                </Groups>
                <Policy changePin="true"/>
                <Rights dual="true" single="true"/>
                <Attributes>
                    <Attribute name="email" value="bob@example.com"/>
                </Attributes>
            </User>
        </Create>
    </AdminRequest>

Update User
-----------

Updates specific elements of an existing user.

.. code-block:: xml

    <AdminRequest secret="MyAdminAgent" version="3.4">
        <Update>
            <User name="bob">
                <Attributes>
                    <Attribute name="email" value="newemail@example.com"/>
                </Attributes>
            </User>
        </Update>
    </AdminRequest>

Delete User
-----------

.. code-block:: xml

    <AdminRequest secret="MyAdminAgent" version="3.4">
        <Delete>
            <User name="bob"/>
        </Delete>
    </AdminRequest>

Purge Deleted Users
-------------------

Purges users marked as deleted from the repository.

.. code-block:: xml

    <AdminRequest secret="MyAdminAgent" version="3.4">
        <PurgeDeleted />
    </AdminRequest>

Send Message
------------

Sends an arbitrary message to a user via their configured transport.

.. code-block:: xml

    <AdminRequest secret="MyAdminAgent" version="3.4">
        <Message>
            <User name="bob">
                <Alert text="Your custom message here" />
            </User>
        </Message>
    </AdminRequest>

User Sub-Elements Reference
---------------------------

When creating or updating users, the following sub-elements are available:

* **Attributes:** Custom fields (e.g., email, phone). Must match attributes defined in *Repository -> Attributes*.
* **Credentials:** ``<Credentials password="secret" pin="1234"/>``.
* **Groups:** Defines membership. ``<Group name="GroupName"/>``.
* **Policy:** Boolean flags including:
    * ``changePin``: User must change PIN.
    * ``disabled``: Account is disabled.
    * ``locked``: Account is locked.
    * ``pinNeverExpires``: PIN expiry rules do not apply.
    * ``inactive``: Account is inactive.
* **Rights:** Boolean flags for access methods: ``dual``, ``single``, ``swivlet`` (mobile), ``helpdesk``.
* **Oath:** Assigns a hardware token. ``<Oath SerialNumber="12345678" />``.

------------------------------

Helpdesk API
============

The Helpdesk API is a subset of administrative functions focused on user support. Unlike the Admin API, the Helpdesk API can interact with **any** repository, not just the one named after the Agent.

**Endpoint:** ``/sentry/AdminXML``
**Root Element:** ``<HelpdeskRequest>``

Reset User
----------

Resets the user's credentials and sends them via their configured alert transport.

.. code-block:: xml

    <?xml version="1.0" ?>
    <HelpdeskRequest secret="MyHelpdeskAgent" version="3.4">
        <Reset repository="ActiveDirectory">
            <User name="bob"/>
        </Reset>
    </HelpdeskRequest>

Send Security Strings
---------------------

Forces the delivery of Dual Channel security strings to the user.

.. code-block:: xml

    <HelpdeskRequest secret="MyHelpdeskAgent" version="3.4">
        <Strings repository="ActiveDirectory">
            <User name="bob"/>
        </Strings>
    </HelpdeskRequest>

Sync Token
----------

Synchronizes an OATH token using two consecutive OTPs.

.. code-block:: xml

    <HelpdeskRequest secret="MyHelpdeskAgent" version="3.4">
        <OathSync>
            <User name="tokenuser"/>
            <OTP1>123456</OTP1>
            <OTP2>456789</OTP2>
        </OathSync>
    </HelpdeskRequest>

------------------------------

Reporting API
=============

The Reporting API allows the extraction of user lists based on specific criteria.

**Endpoint:** ``/sentry/AdminXML``
**Root Element:** ``<AdminRequest>`` containing a ``<Report>`` tag.

User Reports
------------

The ``<Report>`` element supports an optional ``repository`` attribute. Use ``*`` to search all repositories.

**Report Disabled Users**

.. code-block:: xml

    <AdminRequest secret="MySecret" version="3.4">
        <Report repository="*">
            <Disabled/>
        </Report>
    </AdminRequest>

**Report Locked Users**

.. code-block:: xml

    <Report repository="*">
        <Locked/>
    </Report>

**Report Idle Users**

Returns users who have not authenticated since a specific date.

.. code-block:: xml

    <Report>
        <Idle repository="myRepository" since="12-Mar-2007"/>
    </Report>

**All Users**

Returns a list of all users in a repository.

.. code-block:: xml

    <Report repository="*">
        <AllUsers/>
    </Report>

**All Users Detailed**

Returns detailed attributes for all users in a repository.

.. code-block:: xml

    <Report repository="*">
        <AllUsersDetailed/>
    </Report>

**Count Users**

Returns a total count of users and license usage.

.. code-block:: xml

    <Report repository="*">
        <CountUsers/>
    </Report>

**License Information**

Checks license details such as expiry and user count.

.. code-block:: xml

    <SASRequest>
        <Version>3.8</Version>
        <Secret>secret</Secret>
        <Action>GetLicenceInfo</Action>
        <LicenceNumber>your-license-key</LicenceNumber>
    </SASRequest>

------------------------------

API Error Codes
===============

Agent XML Errors
----------------

AGENT_ERROR_AGENT_ACCESS
    The user is not in the correct group to use this agent.

AGENT_ERROR_ACTION_TYPE
    The XML Request contained an unrecognized Action element.

AGENT_ERROR_NO_AUTH
    Swivel does not know how to authenticate this user.

AGENT_ERROR_NO_PIN
    The user has no PIN set.

AGENT_ERROR_AUTH_METHOD_UNSUPPORTED
    This agent cannot authenticate a user using this method (e.g., Single Channel on a Dual Channel agent).

AGENT_ERROR_BAD_OTC
    One-time code was missing or malformed.

AGENT_ERROR_SESSION
    A Session could not be created.

AGENT_ERROR_UNAUTHORIZED
    The Agent is not authorized to use the Swivel server (check IP and Secret).

AGENT_WARN_CHANGE_PIN
    Authentication passed, but the user is required to change their PIN.

Admin XML Errors
----------------

ADMIN_ERROR_DOCUMENT_MALFORMED
    The document was valid XML but not a valid API request.

ADMIN_ERROR_MISSING_NAME
    A required name attribute was missing.

ADMIN_ERROR_UNKNOWN_REPOSITORY
    The supplied repository does not exist.

ADMIN_ERROR_UNSUPPORTED_ATTRIBUTE
    An attribute was sent that does not exist in the server configuration.

------------------------------

Utility Applications
====================

Several utility applications have been developed using these APIs to help manage users. These are Windows command-line applications.

**Prerequisites:**
* .NET Framework.
* An Agent configured on the Swivel server.
* For tools that modify users, the Agent must be set to **Act as Repository**.

Configuration File
------------------
These applications use a ``.config`` file (e.g., ``AssignTokens.exe.config``) which must be edited before use. Key settings include:

* ``PINsafeUrl``: The full URL of the Sentry administration context (e.g., ``https://swivel.local:8080/sentry``). Do not include ``/AdminXML``.
* ``PINsafeSecret``: The shared secret defined in the Agent.
* ``AllowSelfSignedSSL``: Set to ``True`` if using a self-signed certificate.

Swivel Client Library
---------------------
The DLL required by all applications below.
:download:`Download SwivelAdminXMLClient <installers/SwivelAdminXMLClient.zip>`

Assign Tokens
-------------
Assigns OATH tokens to users individually or in bulk.
:download:`Download AssignTokens <installers/AdminAPIAssignTokens.zip>`

*Usage:* ``AssignTokens <username> <tokenid>``

Attribute Manager
-----------------
A form-based application to view and alter custom attributes (Email, Phone, etc.).
:download:`Download AttributeManager <installers/AdminAPIAttributeManager.zip>`

Change PIN
----------
Allows changing a PIN for a single user without knowing the current PIN. Uses the Helpdesk API.
:download:`Download ChangePIN <installers/AdminAPIChangePIN.zip>`

*Usage:* ``ChangePIN username newPIN``

Bulk Set PINs
-------------
Sets PINs for a list of users from a file.
:download:`Download InitialPINs <installers/InitialPINs.zip>`

*Usage:* ``InitialPINs <pin> <filename>``