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

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

Authentication By Attribute

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

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

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

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

Mobile Client Provisioning

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

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

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

Ping

Tests that the Swivel application is available.

<SASRequest>
    <Version>3.6</Version>
    <Action>ping</Action>
</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>

Repositories and Syncs: Users created via the Admin API are assigned to a repository named after the Agent. To manage users, the Agent must have “Act as Repository” enabled. * Create/Update/Delete: Not recommended for standard repositories (like AD) as changes will be overwritten by the next User Sync. * Read: Safe to use on any repository. If you need to read from a standard repository (e.g., “AD”), you can define an Agent with the name “AD” (case-sensitive) to perform read operations.

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>

Read User

Retrieves details of an existing user. If the user exists, the response will include all user details except for credentials.

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

Update User

Updates specific elements of an existing user. Any elements supplied here will overwrite existing values.

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

Delete User

Deletes a user from the repository.

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

Sync Repository

Synchronizes Swivel with a repository (e.g., when an external application populates a repository and requires immediate synchronization).

<AdminRequest secret="MyAdminAgent" version="3.4">
    <Sync>
        <Repository repository="ActiveDirectoryOne"/>
    </Sync>
</AdminRequest>

Purge Deleted Users

Purges users marked as deleted from the repository.

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

Send Message

Sends an arbitrary message to a user via their configured transport (usually Alert or Security String transport).

<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 used for message destinations or info.

  • <Attribute name="email" value="bob@home"/>

• Credentials: Used to set PIN or Password.

  • <Credentials password="secret" pin="1234"/>

• Groups: Defines membership.

  • <Group name="GroupName"/>

• Policy: Boolean flags to apply specific policies to the user:

  • changePin: User must change PIN next authentication.

  • disabled: Account is disabled.

  • locked: Account is locked (Deprecated in 4.2).

  • lockedByAdmin: Account locked by administrator (4.2+).

  • lockedPinExpired: Account locked due to PIN expiry (4.2+).

  • lockedFailures: Account locked due to failure count (4.2+).

  • pinNeverExpires: PIN expiry rules do not apply.

  • inactive: Account is inactive.

• Rights: Boolean flags for access methods:

  • dual: User can use dual channel.

  • single: User can use single channel.

  • swivlet: User can use Mobile Client.

  • pinless: User is PINless.

  • helpdesk: User is a helpdesk operator.

• Oath: Assigns a hardware token.

  • <Oath SerialNumber="12345678" />

Admin API Responses

The API reflects the command submitted. If a command fails, the element will contain FAIL.

Successful Read Response:

<?xml version="1.0"? >
<AdminResponse>
    <Read>
        <User name="ann">
            <Alert/>
            <Groups/>
            <Policy pinNeverExpires="true" disabled="true"/>
            <Rights dual="true" single="true"/>
            <String/>
        </User>
    </Read>
</AdminResponse>

Failed Create Response: (e.g., if the user already exists)

<?xml version="1.0"?>
<AdminResponse>
    <Create>
        <User name="sid">FAIL</User>
    </Create>
</AdminResponse>

---

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. This is equivalent to pressing the RESEND button in the administration console.

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

All Users

Returns a list of all users in a repository.

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

All Users Detailed

Returns detailed attributes for all users in a repository.

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

Count Users

Returns a total count of users and license usage.

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

License Information

Checks license details such as expiry and user count.

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

ADMIN_ERROR_UNSUPPORTED_VERSION

The requested version is higher than the API version supported by the server.

---

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