/
API Examples for Postman

API Examples for Postman

Owned by Mark Unwin
Last updated: Oct 08, 2024
6 min read

Introduction

Here are some examples for using the Open-AudIT API via Postman.

When beginning a new request, we always logon and store the returned cookie for future use. In addition to the cookie, if we want to create a resource (Orgs, Locations, Credentials, Discoveries, et al) we need to provide an access token. An access token is generated with every request (except logon) and any of the last 20 (by default, settable in the configuration) will be accepted. You should always aim to use the last access token issued. An example token is in the Get Device List response, below.

 

Updated for Open-AudIT 3.5.4 onward on 2021-11-29.

Logon

Request

Section

 

 

 

Section

 

 

 

URL

POST

http://localhost/open-audit/index.php/logon

 

Headers

Accept

application/json

 

Body

Type

form-data

 

 

Key

username

admin

 

Key

password

password

Response

{ "access_token": "[]", "active": "y", "dashboard_id": "1", "devices_default_display_columns": "", "edited_by": "Administrator", "edited_date": "2024-10-02 11:40:15", "email": "admin@openaudit", "full_name": "Administrator", "id": 1, "lang": "en", "ldap": "", "list_table_format": "", "name": "admin", "org_id": 1, "orgs": "[1]", "password": "", "roles": [ "admin", "org_admin" ], "toolbar_style": "icontext", "type": "user" }

 

Read Devices

Logon as above, then.

Request

Section

 

 

Section

 

 

URL

GET

http://localhost/open-audit/index.php/devices

Headers

Accept

application/json

Response

Note - restricted to one item in the data array, normally you will retrieve all items.

 

{ "meta": { "action": "collection", "collection": "devices", "request_method": "GET", "remote_addr": "::1", "format": "json", "id": null, "access_token": "60485c922d98010d0b6e9a746b15bd50144eccc18ef8896ad28e1e11fc3f", "baseurl": "http://localhost:8080/", "debug": false, "filtered": 1, "groupby": "", "header": 200, "include": "", "license_string": "", "limit": 1, "microtime": 1728348706.632546, "offset": 0, "properties": [ "devices.id", "devices.icon", "devices.type", "devices.name", "devices.ip", "devices.uuid", "devices.hostname", "devices.dns_hostname", "devices.domain", "devices.dns_domain", "devices.dbus_identifier", "devices.fqdn", "devices.dns_fqdn", "devices.description", "devices.os_group", "devices.os_family", "devices.os_name", "devices.os_version", "devices.manufacturer", "devices.model", "devices.serial", "devices.form_factor", "devices.status", "devices.environment", "devices.class", "devices.function", "devices.org_id", "devices.location_id", "devices.snmp_oid", "devices.sysDescr", "devices.sysObjectID", "devices.sysUpTime", "devices.sysContact", "devices.sysName", "devices.sysLocation", "devices.first_seen", "devices.last_seen", "devices.last_seen_by", "devices.identification", "devices.tags" ], "query_string": "limit=1", "requestor": "", "server_app_version": "5.6.0", "server_platform": "MacOS 15.0.1 Sequoia", "sort": "", "time_start": 1728348706.64449, "time_end": 1728348706.714915, "time_elapsed": "0.08", "total": 111, "timestamp": "2024-10-08 10:51:46", "timezone": "UTC +10:00", "version": 1, "filter": [ { "name": "devices.org_id", "function": "whereIn", "operator": "in", "value": [ "1" ] } ], "received_data": [], "sql": [], "heading": "Devices", "icon": "fa fa-desktop", "data_order": [ "id", "icon", "type", "name", "ip", "uuid", "hostname", "dns_hostname", "domain", "dns_domain", "dbus_identifier", "fqdn", "dns_fqdn", "description", "os_group", "os_family", "os_name", "os_version", "manufacturer", "model", "serial", "form_factor", "status", "environment", "class", "function", "org_id", "location_id", "snmp_oid", "sysDescr", "sysObjectID", "sysUpTime", "sysContact", "sysName", "sysLocation", "first_seen", "last_seen", "last_seen_by", "identification", "tags" ] }, "links": {}, "included": { "antivirus": 8, "audit_log": 140, "bios": 70, "change_log": 12642, "disk": 342, "dns": 0, "edit_log": 3006, "file": 35, "firewall": 3, "firewall_rule": 1073, "executable": 101, "ip": 301, "log": 742, "memory": 128, "module": 619, "monitor": 27, "motherboard": 62, "netstat": 2524, "network": 618, "nmap": 65, "optical": 23, "pagefile": 26, "partition": 422, "policy": 1033, "print_queue": 10, "processor": 77, "route": 947, "server": 65, "server_item": 134, "service": 12164, "share": 47, "software": 43305, "software_key": 35, "sound": 58, "task": 4339, "user": 1689, "user_group": 2375, "variable": 2142, "video": 75, "vm": 89, "windows": 39 }, "logs": [], "data": [ { "id": 5, "type": "devices", "attributes": { "id": 5, "icon": "redhat", "type": "computer", "name": "redhat9", "ip": "192.168.1.53", "uuid": "9d762f99-55cb-5f42-a4ea-3704c5be0333", "hostname": "redhat9", "dns_hostname": "redhat9", "domain": "open-audit.lan", "dns_domain": "open-audit.local", "dbus_identifier": "db348c97aadf4b38847d236483fe9f79", "fqdn": "redhat9.open-audit.lan", "dns_fqdn": "redhat9.open-audit.local", "description": "", "os_group": "Linux", "os_family": "RedHat", "os_name": "Red Hat Enterprise Linux release 9.4 (Plow)", "os_version": "9.4", "manufacturer": "innotek GmbH", "model": "VirtualBox", "serial": "", "form_factor": "Virtual", "status": "production", "environment": "production", "class": "server", "function": "", "org_id": 1, "location_id": 1, "snmp_oid": "", "sysDescr": "", "sysObjectID": "", "sysUpTime": "", "sysContact": "", "sysName": "", "sysLocation": "", "first_seen": "2024-08-27 14:43:31", "last_seen": "2024-09-27 13:20:29", "last_seen_by": "audit_ssh", "identification": "Server from innotek GmbH", "tags": [], "orgs.name": "Default Organisation", "orgs.id": 1, "locations.name": "Default Location", "locations.id": 1, "mycount": "1", "audit_class": "fa fa-check text-success", "audit_text": "Discovered and audited computer.", "ip_padded": "192.168.001.053" } } ] }

 






Create Discovery

Logon as above, then request list of devices (or any available endpoint) so we can use the meta → access_token in our request (see above response).

Request

Section

 

 

 

Section

 

 

 

URL

POST

http://localhost/open-audit/index.php/discoveries

 

Headers

Accept

application/json

 

Body

Type

form-data

 

 

Key

data

   

{         "access_token": "bcb3f959c14f0daf959e3de92e4213201a56bc205e31b63f35c3f9299670",       "type": "discoveries",         "attributes":         {             "description": "Subnet - 192.168.1.0/24",             "match_options": "{\"match_dbus\":\"\",\"match_dns_fqdn\":\"\",\"match_dns_hostname\":\"\",\"match_fqdn\":\"\",\"match_hostname\":\"\",\"match_hostname_dbus\":\"\",\"match_hostname_serial\":\"\",\"match_hostname_uuid\":\"\",\"match_ip\":\"\",\"match_ip_no_data\":\"\",\"match_mac\":\"\",\"match_mac_vmware\":\"\",\"match_serial\":\"\",\"match_serial_type\":\"\",\"match_sysname\":\"\",\"match_sysname_serial\":\"\",\"match_uuid\":\"\"}",             "name": "My Testing Discovery",             "org_id": 1,             "scan_options": "{\"exclude_ip\":\"\",\"exclude_tcp_ports\":\"\",\"exclude_udp_ports\":\"\",\"filtered\":\"\",\"id\":\"1\",\"nmap_tcp_ports\":\"\",\"nmap_udp_ports\":\"\",\"open|filtered\":\"\",\"ping\":\"\",\"service_version\":\"\",\"ssh_ports\":\"\",\"tcp_ports\":\"\",\"timeout\":\"\",\"timing\":\"\",\"udp_ports\":\"\",\"script_timeout\":\"\",\"snmp_timeout\":\"\",\"ssh_timeout\":\"\",\"wmi_timeout\":\"\"}",           "subnet": "192.168.1.0/24",             "type": "subnet"       }     }

Response

Note, generated from a discoveries read. The actual output should be almost identical.

{ "data": [ { "attributes": { "ad_domain": "", "ad_server": "", "cloud_id": 1, "cloud_name": "", "command_options": "", "description": "Subnet - 192.168.1.0/24", "devices_assigned_to_location": null, "devices_assigned_to_org": null, "discard": "n", "duration": "00:00:00", "edited_by": "Administrator", "edited_date": "2021-11-29 13:16:53", "id": 3, "ip_all_count": 0, "ip_audited_count": 0, "ip_discovered_count": 0, "ip_responding_count": 0, "ip_scanned_count": 0, "last_finished": "2000-01-01 00:00:00", "last_run": "2000-01-01 00:00:00", "match_options": { "match_dbus": "", "match_dns_fqdn": "", "match_dns_hostname": "", "match_fqdn": "", "match_hostname": "", "match_hostname_dbus": "", "match_hostname_serial": "", "match_hostname_uuid": "", "match_ip": "", "match_ip_no_data": "", "match_mac": "", "match_mac_vmware": "", "match_serial": "", "match_serial_type": "", "match_sysname": "", "match_sysname_serial": "", "match_uuid": "" }, "name": "My Testing Discovery", "network_address": "", "org_id": 1, "orgs.id": 1, "scan_options": { "exclude_ip": "", "exclude_tcp_ports": "", "exclude_udp_ports": "", "filtered": "", "id": "1", "nmap_tcp_ports": "", "nmap_udp_ports": "", "open|filtered": "", "ping": "", "script_timeout": "", "service_version": "", "snmp_timeout": "", "ssh_ports": "", "ssh_timeout": "", "tcp_ports": "", "timeout": "", "timing": "", "udp_ports": "", "wmi_timeout": "" }, "seed_ip": "", "seed_ping": "y", "seed_restrict_to_private": "y", "seed_restrict_to_subnet": "y", "status": "", "subnet": "192.168.1.0/24", "system.id": 0, "system_id": 0, "type": "subnet" }, "id": 3, "links": { "self": "http://dev.local/omk/open-audit/discoveries/3" }, "type": "discoveries" } ], "included": [], "issues": [], "meta": { "access_token": "ef4421add7e6f2741a2830a1b0262d3b678cc33efdacdd9442d5a871f474", "action": "read", "as_at": "", "baseurl": "http://dev.local/omk/open-audit", "collection": "discoveries", "current": "y", "data_order": [ "discoveries.id", "discoveries.name", "discoveries.org_id", "discoveries.description", "discoveries.type", "discoveries.subnet", "discoveries.seed_ip", "discoveries.seed_restrict_to_subnet", "discoveries.seed_restrict_to_private", "discoveries.seed_ping", "discoveries.ad_domain", "discoveries.ad_server", "discoveries.devices_assigned_to_org", "discoveries.devices_assigned_to_location", "discoveries.network_address", "discoveries.system_id", "discoveries.scan_options", "discoveries.match_options", "discoveries.command_options", "discoveries.discard", "discoveries.last_run", "discoveries.last_finished", "discoveries.duration", "discoveries.status", "discoveries.ip_all_count", "discoveries.ip_responding_count", "discoveries.ip_scanned_count", "discoveries.ip_discovered_count", "discoveries.ip_audited_count", "discoveries.cloud_id", "discoveries.cloud_name", "discoveries.edited_by", "discoveries.edited_date", "orgs.id", "system.id" ], "debug": false, "filter": [], "filtered": 1, "format": "json", "groupby": "", "header": "HTTP/1.1 200 OK", "heading": "Discoveries", "id": 3, "include": "", "limit": 1000, "nmap_version": 7, "offset": 0, "properties": ".*", "query_parameters": [], "query_string": "", "received_data": [], "request_method": "GET", "requestor": "commercial", "server_app_version": "4.3.0", "server_platform": "Debian GNU/Linux 9 (stretch)", "sort": "", "sub_resource": "", "timestamp": "2021-11-29 13:24:45", "timezone": "UTC +1000", "total": 1, "version": 1 } }

 

Update Discovery

Logon as above, then.

Request

Section

 

 

 

Section

 

 

 

URL

PATCH

http://localhost/open-audit/index.php/discoveries/5

 

Headers

Accept

application/json

 

Body

Type

x-www-form-urlencoded

 

 

Key

data

{    "id": 5,    "type": "discoveries",    "attributes": {       "name": "My New Name OMK"    } }

Response

Note - generated from pre 3.5.4. Attribute outputs will be as above for 3.5.4 onward.

{ "data": [ { "attributes": { "description": "Subnet - 192.169.1.0/24", "devices_assigned_to_location": null, "devices_assigned_to_org": null, "discard": "n", "duration": "00:00:00", "edited_by": "Administrator", "edited_date": "2020-03-24 14:13:36", "id": 5, "ip_all_count": 0, "ip_audited_count": 0, "ip_discovered_count": 0, "ip_responding_count": 0, "ip_scanned_count": 0, "last_finished": "2000-01-01 00:00:00", "last_run": "2000-01-01 00:00:00", "name": "My New Name OMK", "network_address": "http://127.0.0.1/open-audit/", "options": "", "org_id": 1, "orgs.id": 1, "other": { "nmap": { "discovery_scan_option_id": "1", "exclude_ip": "", "exclude_tcp_ports": "", "exclude_udp_ports": "", "filtered": "n", "nmap_tcp_ports": "0", "nmap_udp_ports": "0", "ping": "y", "service_version": "n", "ssh_ports": "22", "tcp_ports": "22,135,62078", "timeout": "0", "timing": "4", "udp_ports": "161" }, "subnet": "192.169.1.0/24" }, "status": "", "system.id": 0, "system_id": 0, "type": "subnet" }, "id": 5, "links": { "self": "/omk/open-audit/discoveries/5" }, "type": "discoveries" } ], "errors": [], "included": [], "links": { "first": null, "last": null, "next": null, "prev": null, "self": "http://localhost/omk/open-audit/discoveries/5" }, "meta": { "access_token": "47049142d113e4e316ae4219afdf54d6a6d034ff779a42fd5198a720da2e", "action": "update", "baseurl": "http://localhost/omk/open-audit", "collection": "discoveries", "current": "y", "data_order": [ "discoveries.id", "discoveries.name", "discoveries.org_id", "discoveries.description", "discoveries.type", "discoveries.devices_assigned_to_org", "discoveries.devices_assigned_to_location", "discoveries.network_address", "discoveries.system_id", "discoveries.options", "discoveries.discard", "discoveries.last_run", "discoveries.last_finished", "discoveries.duration", "discoveries.status", "discoveries.ip_all_count", "discoveries.ip_responding_count", "discoveries.ip_scanned_count", "discoveries.ip_discovered_count", "discoveries.ip_audited_count", "discoveries.edited_by", "discoveries.edited_date", "orgs.id", "system.id", "other.subnet", "other.nmap" ], "debug": false, "filter": [], "filtered": "", "format": "json", "groupby": "", "header": "HTTP/1.1 200 OK", "heading": "Discoveries", "id": 5, "ids": 0, "include": "", "limit": 1000, "offset": 0, "properties": "*", "query_parameters": [], "query_string": "", "received_data": { "attributes": { "id": 5, "name": "My New Name OMK" }, "id": 5, "type": "discoveries" }, "request_method": "PATCH", "requestor": "", "sort": "", "sub_resource": "", "sub_resource_id": 0, "timestamp": "2020-03-24 14:13:36", "timezone": "UTC +1000", "total": 0, "version": 1 } }

 

 

Delete Discovery

Logon as above, then.

Request

Section

 

 

Section

 

 

URL

DELETE

http://localhost/open-audit/index.php/discoveries/5

Headers

Accept

application/json

Response

 

{ "meta": { "access_token": "530d34dc6304ebd361d088d7831e4ce9d276ac8a4826837bdf36e8e84c87", "action": "delete", "baseurl": "http://localhost/open-audit/", "collection": "discoveries", "current": "y", "debug": false, "filtered": "", "format": "json", "groupby": "", "header": "HTTP/1.1 200 OK", "id": 5, "ids": 0, "include": "", "limit": 1000, "offset": 0, "properties": "*", "query_string": "", "request_method": "DELETE", "requestor": "", "sort": "", "sub_resource": "", "sub_resource_id": 0, "total": 0, "timestamp": "2020-03-24 14:22:38", "timezone": "UTC +1000", "version": 1, "filter": [], "query_parameters": [], "received_data": [], "heading": "Discoveries", "data_order": [] }, "links": { "self": "http://localhost/open-audit/index.php/discoveries/5", "first": null, "last": null, "next": null, "prev": null }, "included": [], "data": [ { "type": "discoveries" } ] }

 

 

Related content