Documentation Center

AlienVault® APIs

AlienVault publishes APIs for USM Anywhere™ and USM Central™. These REST APIs provide a programmatic interface that allows you to access your AlienVault data directly from your own applications and extensions. These 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 JSON, including those with errors.

Connections

All connections should use the HTTPS protocol on port 443 using the public DNS for your subdomain, such as the following syntax.

GET https://mysubdomain.alienvault.cloud/api/2.0/alarms

Authentication

AlienVault uses the OAuth 2.0 standard for token endpoint security. Use the oauth/token endpoint to request a token used for authentication by the other API endpoints. Before you can retrieve a token, you must create a Client ID/Client Secret pair in USM Central or USM Anywhere for your user account.

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

There is a single www-form-urlencoded POST parameter, grant_type. The username is the Client ID and the password is the Client Secret.

Note: The AlienVault REST APIs currently support only a single grant_type value of client_credentials.

The response to this POST 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"
	}

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.

Send the token in the header on subsequent requests to the other endpoints.

   Authorization: Bearer <access_token>

Requests and Responses

Most endpoints support standard REST paradigms, such as GET a collection (GET https://mysubdomain.alienvault.cloud/api/2.0/alarms)or GET a member of a collection (GET https://mysubdomain.alienvault.cloud/api/2.0/alarms/{alarmId}).

Collection responses are JSON objects with a structure that allows pagination using HATEOAS-style links:

{
  "_links": {
    "first": {
      "href": "https://your-subdomain.alienvault.cloud/api/2.0/alarms?page=0&size=20&sort=timestamp_occured,desc",
      "templated": false
    },
    "self": {
      "href": "https://your-subdomain.alienvault.cloud/api/2.0/alarms",
      "templated": false
    },
    "next": {
      "href": "https://your-subdomain.alienvault.cloud/api/2.0/alarms?page=1&size=20&sort=timestamp_occured,desc",
      "templated": false
    },
    "last": {
      "href": "https://your-subdomain.alienvault.cloud/api/2.0/alarms?page=175&size=20&sort=timestamp_occured,desc",
      "templated": false
    }
  },
  "_embedded": {
    "alarms": [
        ... content omitted for clarity ...
    ]
  },
  "page": {
    "size": 20,
    "totalElements": 3506,
    "totalPages": 176,
    "number": 0
  }
}

Single-item responses are JSON objects that represent the resource state.

{
	"uuid": "971918fd-a569-548a-5a80-1ffcda2a8365",
	"has_alarm": false,
	"needs_enrichment": true,
	"priority": 20,
	"suppressed": false,
	"destinations": [],
	"sources": [],
	"events": [
		... content omitted for clarity ...
				],
	"_links": {
			"self": {
			"href": "https://your-subdomain.alienvault.cloud/api/2.0/alarms/971918fd-a569-548a-5a80-1ffcda2a8365",
			"templated": false
				}
			}
	

HTTP Status Codes

Responses can include one of the following HTTP status codes, 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 AlienVault software specific cause differs from the following standard.

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.

Rate Limiting

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

Log Access

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