MFA Agent Lookup REST APIMFA Agent Lookup REST API
This customer-facing REST API can look up an MFA Agent tracking record by its Software ID or hostname.
AuthenticationAuthentication
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 RolesAdministrative 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 KitSoftware Developer Kit
You can download the API Software Developer Kit (SDK) from Cloud Administration REST API Download.
Request RequirementsRequest Requirements
RequestRequest
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 MethodHTTP Method
HTTP POST is the method required to communicate with the REST endpoint. Service requests using any other HTTP methods will be refused.
Request HeadersRequest 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 BodyRequest 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 ParametersRequest 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 DataExample 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 BodyExample Request Body
{
"SOFTWARE_ID": "7d37f23f-6e47-4fc1-8334-05a39cdc98c6"
}
ResponseResponse
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
|
403 |
The request is denied due to insufficient access permissions. The cause may be
|
404 |
The specified MFA Agent record cannot be found. The cause may be
|
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 BodyResponse 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 |
ExampleExample
{ "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" } |