=============
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).

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

* **Method:** HTTP POST.
* **Format:** XML Request and XML Response.
* **Ports:** Typically ``8080`` (HTTP) or ``443`` (HTTPS/Proxy), depending on appliance configuration.
* **Contexts:**
    * Authentication requests go to: ``/sentry/AgentXML``.
    * Admin, Helpdesk, and Reporting requests go to: ``/sentry/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>
   

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>
   

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.

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>
   

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``, ``disabled``, ``locked``, ``pinNeverExpires``.
* **Rights:** Boolean flags for access methods: ``dual``, ``single``, ``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>
   

**Count Users**

Returns a total count of users and license usage.

.. code-block:: xml

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

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

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

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