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.

<?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:

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

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

Response:

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

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

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

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

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

Delete User

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

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

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

Sync Token

Synchronizes an OATH token using two consecutive OTPs.

<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

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

Report Locked Users

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

Report Idle Users

Returns users who have not authenticated since a specific date.

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

Count Users

Returns a total count of users and license usage.

<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 SwivelAdminXMLClient

Assign Tokens

Assigns OATH tokens to users individually or in bulk. Download AssignTokens

Usage: AssignTokens <username> <tokenid>.

Attribute Manager

A form-based application to view and alter custom attributes (Email, Phone, etc.). Download AttributeManager

Change PIN

Allows changing a PIN for a single user without knowing the current PIN. Uses the Helpdesk API. Download ChangePIN

Usage: ChangePIN username newPIN.

Bulk Set PINs

Sets PINs for a list of users from a file. Download InitialPINs

Usage: InitialPINs <pin> <filename>.