MFA Agent Lookup REST API

This customer-facing REST API can look up an MFA Agent tracking record by its Software ID or hostname.

Authentication

Clients calling this API must authenticate themselves by including a JSON Web Token in a request. For instructions on using this token, see Authentication for the Cloud Administration APIs .

Administrative Roles

This API can use an API key that is associated with either the Super Administrator or Help Desk Administrator role. For more information, see Manage the Cloud Administration API Keys.

Software Developer Kit

You can download the API Software Developer Kit (SDK) from Cloud Administration REST API Download.

Request Requirements

Request

REST Endpoint

The URL format of the MFA Agent lookup API is shown as follows.

https://<RSA Cloud Administrative Console URL>/AdminInterface/restapi/v1/agents/lookup

HTTP Method

HTTP POST is the method required to communicate with the REST endpoint. Service requests using any other HTTP methods will be refused.

Request Headers

The Authorization header must contain a JSON Web Token (JWT) generated from the API Access Key created by a Super or Helpdesk Administrator. A request without a valid JWT will be denied service.

In addition, the Content-Type header must be "application/json".

Request Body

The body of the request is a JSONized string that includes the request parameters described below. The name of each parameter is case sensitive, and at least one of the two parameters is required. If both parameters are provided, the cloud service attempts to find the MFA Agent using first the Software ID and then the hostname only if the first attempt did not succeed.

Request Parameters

Name

Details

Required?
SOFTWARE_ID

Specifies the software ID of the MFA Agent to search. It must be a UUID representation and cannot exceed 36 characters long. The SOFTWARE ID can be found from the agent installation.

Example: In Windows this value is located in the Windows registry:

Key: HKLM\SOFTWARE\RSA\RSA MFA Agent for Microsoft Windows\CurrentVersion

Value: SoftwareID

At least one of these Request Parameters is required. A second parameter is optional.
HOSTNAME Specifies the hostname of the MFA Agent to search. It cannot exceed 255 characters long. At least one of these Request Parameters is required. A second parameter is optional.

Example Request Data

The following example displays a request.

POST /AdminInterface/restapi/v1/agents/lookup

Authorization : Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJmOWU2MjY2OS00NjU4LTRlMTgtYmUxMS0yZWZiMmQ5MDIxZTMiLCJhdWQiOiJodHRwczpcL1wvbW9rbzItc3ltLmFjY2Vzcy1kZXYuc2VjdXJpZC5jb21cL0FkbWluSW50ZXJmYWNlXC9yZXN0YXBpXC8iLCJleHAiOjE2MjM1MTU0MTAsImlhdCI6MTYyMzUxMTgxMH0.Y7V5BmZyInwoieQFpXWhH6B0O9Nbc_0ZUGwvguH9hiOe3WbdYtJX3IVTNoOnVsktPZPazYoNubuk9m2eZCqRPATnHBagkaeKRQqNc212zanQxF5rshgC8HJKfSFzK5CMFzVPAa4sdzwx3ArtsCXdWjRMNreGBmsbUNA42-n82ta36_iTHjsrk4UpZrW1ZUaVH5XXNa7K-1AZQQvmQQW7GadbXdsA8x0J4qw5l7HfhgIsnbQm7d-yxCZ12yoY-GNfVfE23wZsz6Be3iNwMS8zHQDApBczBUjGyJnhlZVMAplKBO-ZNHY8yyTzIaGAaPIY4z486JY_0zNN9tBF2WkR0Q,

Content-Type : application/json

Example Request Body

{

"SOFTWARE_ID": "7d37f23f-6e47-4fc1-8334-05a39cdc98c6"

}

Response

A successful response consists of the HTTP status 200 and a payload that includes details of the MFA Agent. Below is a list of possible HTTP status code in the response.

Response Codes

HTTP Status Code

Description
200 The MFA Agent has been successfully retrieved. Response body contains details of the MFA Agent.
400

The request is missing or contains invalid parameters.

The cause may be

  • missing request parameters

  • invalid UUID format, or

  • invalid text length
403

The request is denied due to insufficient access permissions.

The cause may be

  • the lack of administration role, or

  • an invalid Json Web Token (JWT), or

  • the Agent tracking feature has not been enabled.
404

The specified MFA Agent record cannot be found.

The cause may be

  • an incorrect REST endpoint, or

  • nonexistent MFA Agent.
409

Multiple MFA Agents have been found with the given search parameters. The cause may be due to that the software ID was not provided and that there were multiple MFA Agents sharing the same hostname.

Provide the software ID or a unique hostname in the request parameters.
500

The request cannot be serviced due to an internal server error.
503

The service being requested is not available.

Response Body

Upon success (HTTP status 200), the response body will include details of the MFA Agent.

Property Description Data Type
softwareID a unique identifier of the MFA Agent generated by the Agent installer during installation and provided by the Agent during an authentication request. This value will always be returned. string representation of a UUID
clientID the name of the MFA Agent optionally provided by the Agent during an authentication request. This value will be optional, depending on the availability of the information. string
agentType the Agent type provided by the Agent during an authentication request. This value will always be returned.

string
version the version of the MFA Agent optionally provided by the Agent during an authentication request. This value will depend on the availability of the information. string
platform the OS platform on which the MFA Agent is installed and optionally provided by the Agent during an authentication request. This value will depend on the availability of the information.

string
hostname the fully qualified hostname of the system on which the MFA Agent is installed and provided by the Agent during an authentication request. This value will always be returned.

string
initiatingIp the IP address of the system from which the MFA Agent is making the authentication request. This value will depend on the availability of the information. string representation of an IP address
firstSeenUTC the UTC date on which the MFA Agent was first recorded by the cloud service. This value is managed by CAS. string representation of an ISO date
lastAuthenticationUTC the UTC date on which a successful authentication was last recorded by the cloud service; may be blank if there's no successful authentication from the Agent. This value is managed by CAS. string representation of an ISO date
lastOfflineDownloadUTC the UTC date on which an offline download was last requested by the MFA Agent; may be blank if there's no offline download request from the Agent. This value is managed by CAS. string representation of an ISO date
lastOfflineDataUTC the last valid UTC date of the offline download data by the MFA Agent before expiration; may be blank if there's no offline download request from the Agent. This value is managed by CAS. string representation of an ISO date

Example

{

"softwareId": "7d37f23f-6e47-4fc1-8334-05a39cdc98c6",

"clientId": "Transfer-Data-feed-2022",

"agentType": "RSA MFA Agent for Windows",

"version": "2.1.0.0",

"platform": "Microsoft Windows 11",

"hostname": "Aqn3fpuG.rsa.com",

"initiatingIp": "172.24.5.112",

"firstSeenUTC": "2022-03-08",

"lastAuthenticationUTC": "2022-03-15",

"lastOfflineDownloadUTC": "2022-03-14",

"lastOfflineDataUTC": "2022-03-22"

}