USM Central APIs

AT&T Cybersecurity publishes Application Programming Interfaces (APIs) for USM Central™ version 1.1. These Representational State Transfer (REST) APIs provide a programmatic interface that enables you to access your USM Central data directly from your own applications and extensions. The APIs are organized around basic REST principles, with easy-to-understand, resource-oriented URLs, and use HTTP response codes to indicate API errors. All API responses return JavaScript Object Notation (JSON), including those with errors.

Edition: Access to the USM Central APIs is limited to Standard and Premium accounts.

See https://cybersecurity.att.com/pricing for more information about the features and support provided by each of the USM Anywhere editions.

Authentication

The USM Central APIs use OAuth 2.0 for endpoint protection, which provides token-based authentication and authorization on the Internet. The diagram below illustrates the authorization flow between the user and the USM Central APIs.

Before you can retrieve a token, you must create a client ID and secret code in USM Central for your user account.

Important: Only USM Central users of the Manager role can create new API clients.

To get your client ID and secret code

  1. Click the icon and select Profile Settings.
  2. On the Profile page, select the API Clients tab.
  3. Click New Client.

    The system generates the Client ID and secret code.

    Note: This code is only available when it is first generated, so be sure to keep it secure and copy it when it is displayed. If you want to generate a new code, delete the current client and create a new one.

Then, you need to use the oauth/token endpoint to request a token used for authentication by the other API endpoints. For example:

curl -X POST "https://<your-subdomain>.alienvault.cloud/api/{version}/oauth/token?grant_type=client_credentials" \
     -d @request_body \
     --user <username>:<password>

The POST command has a single www-form-urlencoded parameter, grant_type, and currently the only supported value is client_credentials. Use the client ID for username and the secret code for password.

The response to this POST command contains the OAuth token that must be used to make subsequent requests to the other API endpoints.

{
	"access_token": "xxx.yyy.zzz",
	"token_type": "bearer",
	"expires_in": 899,
	"scope": "trust read write",
	"jti": "3b4cc123-2164-44cb-ae34-9c76d7c429ab"
}

Note: The OAuth access token expires after 15 minutes. When or before it expires, you must use the oauth/token endpoint to re-authenticate and get a new token.

Next, you must use the token in the header on subsequent requests to the other endpoints. For example:

Authorization: Bearer <access_token>

Requests and Responses

All connections should use the HTTPS protocol using the public Domain Name System (DNS) name for your subdomain. For example:

GET https://<your-subdomain>.alienvault.cloud/api/1.1/deployments

GET https://<your-subdomain>.alienvault.cloud/api/1.1/alarms/{alarmId}

A given client is limited to 100 GET and 50 POST requests per second for a USM Central subdomain. When exceeding the threshold, a 429 response is returned until you are back under the rate limit.

Most endpoints in the USM Central APIs support standard REST paradigms. You can either retrieve a collection or a member of a collection.

Get a Collection

Enter this request to get a colleciton:

GET https://<your-subdomain>.alienvault.cloud/api/1.1/deployments

You will receive this response for the request:


[
	{
		"id": "cn://<your-subdomain>.alienvault.cloud",
		"licenseKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		"fqdn": "<your-subdomain>.alienvault.cloud",
		"name": "<your-subdomain>",
		"displayName": "<your-subdomain>",
		"type": "USM Anywhere",
		"joinedSince": 1624876043779,
		"connectionStatus": "connected",
		"authorized": true					
	}  
]

Collection responses are JSON objects with a structure that allows pagination using Hypermedia as the Engine of Application State (HATEOAS)-style links. See USM Central API References for more examples.

Get a Member of a Collection

Enter this request to get a member of a collection:

GET https://<your-subdomain>.alienvault.cloud/api/1.1/alarms/{alarmId}

Important: The AlienVault APIs can only access alarm and event data stored in the local system; raw logs in cold storage are not accessible by the API calls.

You will receive this response for the request:

{
	"events": [...
	],
 	"@timestamp": "2021-07-28T22:20:17.211Z",
 	"alarm": { ...
	},
	"licenseId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
	"timestamp": 1627510817201,
	"msspId": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
 	"@version": 1,
 	"assets": [],
	"tenantId": "cn://<your-subdomain>.alienvault.cloud"
}

Single-item responses are JSON objects that represent the resource state. See USM Central API References for the complete example.

HTTP Status Codes

Responses can include one of the HTTP status codes listed in the table below, in addition to content data. Status codes are not part of endpoint descriptions because the implementation follows the HTTP standard for reporting status. However, the API reference documentation notes status codes with special significance for the endpoint, or where the USM Central API specific cause differs from the following standard.

Standard HTTP status codes and descriptions
Status Code Generalized Description
200 Request completed successfully.
201 Create request completed successfully.
400 Request error. See response body for details.
401 Authentication failure, invalid access credentials.
403 Insufficient permission.
404 Requested endpoint does not exist.
409 Invalid operation for this endpoint. See response body for details.
429 Rate limit for this operation has been reached.
500 Unspecified internal server error. See response body for details.