Online Help

API quick reference

Updated in 23.10

The AlloyScan API allows external software applications to integrate and collaborate with the services and data provided by AlloyScan. This integration involves exchanging data, performing actions, or using specific functionality provided by AlloyScan.

This document describes general concepts and covers key tasks performed via the API, including obtaining an authentication token, listing devices, and retrieving information about a specific device.

General concepts

To execute an API command, you need to specify its components, including the HTTP method, the API's base URL (e.g., https://alloyscan.example.com/api), and the request header. Additionally, you must determine the data format you intend to send, which can be one of the following:

  • application/x-www-form-urlencoded

  • application/json

To ensure that the API server correctly interprets the data you're sending, include the corresponding Content-Type header in your request:

  • Content-Type: application/x-www-form-urlencoded

  • Content-Type: application/json

Obtaining authentication token

You must obtain an API access token and then specify it in the Authorization header of every request sent to the API.

API access tokens are unique identifiers associated with your AlloyScan account, allowing you to interact with AlloyScan securely.

IMPORTANT: The access token remains valid for a brief period (one hour) to prevent a security breach.

Once you have a token, you can specify it in the Authorization header when sending requests to the API as follows:

Authorization: bearer <token>

To obtain an authentication token using your client credentials, send a POST request described below.

HTTP method

POST

API URL

https://alloyscan.example.com/identity-server/connect/token

Header

IMPORTANT: Currently, this endpoint can be sent only in the application/x-www-form-urlencoded format.

  • Content-Type: application/x-www-form-urlencoded

Parameters

  • client_id: Your client ID in AlloyScan.

  • client_secret: The client secret associated with your client ID.

  • grant_type: The OAuth 2.0 grant type. This must be set to client_credentials.

  • scope: The scope parameter defines the level of access or permissions that your application is requesting. This must be set to api_client.

Request example

Header

Content-Type: application/x-www-form-urlencoded

Body

client_id=<YOUR CLIENT ID>&client_secret=<YOUR CLIENT SECRET>&grant_type=client_credentials&scope=api_client

cURL command

To try out this example, use the following cURL command. Make sure to replace the <YOUR CLIENT ID> and <YOUR CLIENT SECRET> placeholders with your actual client ID and password.

curl -X POST \
	-H "Content-Type: application/x-www-form-urlencoded" \
	-d "client_id=<YOUR CLIENT ID>&client_secret=<YOUR CLIENT SECRET>&grant_type=client_credentials&scope=api_client" \
	https://alloyscan.example.com/identity-server/connect/token

Response

Upon successful validation, the API responds with a token in JSON format, which can be used by your application to authenticate subsequent API requests.

Obtaining a list of devices

To retrieve a comprehensive list of audited devices associated with a specific site, send a POST request described below.

HTTP method

POST

API URL

https://alloyscan.example.com/api/audit-data/sites/<SITE ID>

where <SITE ID> is the GUID of a specific site.

You can obtain that GUID from the UI as follows:

  1. Access the Admin Center.

  2. Navigate to any section relevant to the target site.

  3. View the URL in the browser's address bar. The hexadecimal string between /admin-center/ and the section name (such as /identity/users) is the site GUID.

Parameters in the request body

Additional parameters can be specified in the request body.

  • filter: Specify filtering criteria for the data you want to retrieve. If set to null, no specific filtering criteria are applied.

  • sorting: Define the sorting order for the retrieved data.

  • column: Specifies the column by which the data should be sorted, e.g., "name".

  • isDesc: Determines the sorting direction. When set to true, it indicates a descending sorting order; when set to false, it indicates an ascending sorting order.

  • columns: Specify which columns you want to include in the response. When left empty, the response will include default columns.

  • offset: This field is used to determine the starting point from which the data should be retrieved. If set to 0, the retrieval will begin from the beginning of the result set, fetching the first set of audited devices.

Request examples

Request in the application/x-www-form-urlencoded format

Header

Authorization: bearer <token>

Content-Type: application/x-www-form-urlencoded

URL

https://alloyscan.example.com/api/audit-data/sites/<SITE ID>

Request body

filter=&sorting[column]=name&sorting[isDesc]=false&columns=&offset=0

cURL command

To try out this example, use the following cURL command. Make sure to replace <token> with the actual access token you have for authorization and <SITE ID> with your actual site ID.

curl -X POST \
	-H "Authorization: Bearer <token>" \
	-H "Content-Type: application/x-www-form-urlencoded" \
	-d "filter=&sorting[column]=name&sorting[isDesc]=false&columns=&offset=0" \
	https://alloyscan.example.com/api/audit-data/sites/<SITE ID>

Request in the JSON format

Header

Authorization: bearer <token>

Content-Type: application/json

Body
{
	"filter": null,
	"sorting": {
		"column": "name",
		"isDesc": false
	},
	"columns": [],
	"offset": 0
}
cURL command

To try out this example, use the following cURL command. Make sure to replace <token> with the actual access token you have for authorization and <SITE ID> with your actual site ID, such as 7f-a9-4c-b1ef.

curl -X POST \
	-H "Authorization: Bearer <token>" \
	-H "Content-Type: application/json" \
	-d '{
		"filter": null
		"sorting": {
			"column": "name",
			"isDesc": false
		},
		"columns": [],
		"offset": 0
	}' \
	https://alloyscan.example.com/api/audit-data/sites/<SITE ID>

Response example

Upon successful validation, the API retrieves a detailed list of audited devices, resulting in output similar to the following:

{
	"data": [
		{
			"id": "d4-2a-42f5-c3-6ba"
			"auditId": "fab838b3-b-a422451be226",
			"legacyAuditId": "SSERVER_X919G",
			"tags": [],
			"auditDate": "2023-11-20T00:12:07.095093Z",
			"siteId": "7f-a9-4c-b1ef",
			"deviceTypeId": "56-793991b1",
			"deviceSubTypeId": null,
			"auditServiceId": "87-95aa",
			"auditedBy": "tyler",
			"isAgent": false,
			"lastAuditTaskId": "beab33f-7b2df",
			"lastAuditTaskStatus": "Success",
			"lastAuditTaskDate": "2023-11-20T00:12:13.025526Z",
			"schedulerName": "q",
			"nextAuditDate": "2023-11-21T00:09:00Z",
			"credentialsId": "f9-900",
			"schedulerIds": [
				"3e-f183-154f"
			],
			"name": "SSERVER",
			"data": {
				"network": {
					"ipAddress": "17.10.30.11"
				}
			}
			"software": null,
			"customData": null,
			"lastSegmentId": null,
			"lastSeenDate": "2023-11-20T00:12:07.095093Z",
			"modifierInfo": null,
			"modified": "0001-01-01T00:00:00"
		},...
		],
	"nextOffset": null
}

Obtaining details of an audited device

To retrieve comprehensive details of a specific audited device, send a GET request described below.

HTTP method

GET

API URL

https://alloyscan.example.com/audit-data/full-data/<ID>

where <ID> is the ID of the specific audited device you wish to access detailed information about. You can get that ID from the list of devices for a site, as described earlier.

Alternatively, you can obtain a device ID from the UI, as follows:

  1. Access the Inventory section, where you can find all audited devices. For details, see Managing your IT inventory.

  2. Click the target device to bring out the details.

  3. View the URL in the browser's address bar. The hexadecimal string between /inventory/grid/ and the tab header (such as /general) is the device ID (GUID).

Request example

Header

Authorization: bearer <token>

Content-Type: application/x-www-form-urlencoded

or

Content-Type: application/json

URL

https://alloyscan.example.com/api/audit-data/full-data/<ID>

cURL command

To try out this example, use the following cURL command. Make sure to replace <token> with the actual access token you have for authorization and <ID> with your actual device ID, such as d4-2a-42f5-c3-6ba.

Request in the application/x-www-form-urlencoded format
curl -X GET \
	-H "Authorization: bearer <token>" \
	-H "Content-Type: application/x-www-form-urlencoded" \
	https://alloyscan.example.com/api/audit-data/full-data/<ID>
Request in the JSON format
curl -X GET \
	-H "Authorization: bearer <token>" \
	-H "Content-Type: application/json" \
	https://alloyscan.example.com/api/audit-data/full-data/<ID>

Response example

Upon successful validation, the API retrieves comprehensive details about the specified device, resulting in output similar to the following:


{
	"id": "7734-c57",
	"name": "ATYLER",
	"networkAddress": "ATYLER",
	"macAddress": "94:6D",
	"hypervisorPlatform": null,
	"auditId": "6f0-6d07",
	"dnsName": "ATYLER.acme-software.com",
	"domainWorkgroup": "ACME-NY",
	"ipv4Address": "130.20.10",
	resolvedIpv4Address": "130.20.10",
	"manufacturer": "GIGA-BYTE TECHNOLOGY CO.,LTD.",
	"snmpVersion": null,
	"snmpSysObjectId": null,
	"tags": [
	],
	"auditEnableStatus": 1,
	"auditEnableErrorMessage": "",
	"auditAgentData": null,
	"auditStatus": {
		"dnsCheck": 0,
		"agent": 4,
		"deviceType": 0,
		"testConnection": 0,
		"trustedConnection": 0,
		"accessError": 0,
		"psRemoting": 0
	},
	"deviceIds": [
		{
			"origin": "uuid",
			"value": "03D-6D0709"
		},
		{
			"origin": "device-id",
			"value": "{6F0-82DE-D48}"
		}
	],
	"segmentId": "f19-8f1",
	"deviceTypeId": "566-791b1",
	"deviceSubTypeId": null,
	"auditDataId": null,
	"modifierInfo": {
		"clientType": 1,
		"title": "JOHNDOE",
		"userId": "f8b5"
	},
	"modified": "2023-05-10T18:54:25.232269Z"
}