End User GuideRelease NotesCustomer Support Portal
Administrator Guide

Atmos Cloud API: Locations

Suggest Edits

The Atmos Cloud API allows administrators to have programmatic control over locations. Click here to learn more about generating an API token.

📘

NOTE

This is a limited release feature. For more information contact Axis Security Support: [email protected]

Locations

Create a new location

The management API allows administrators to create new location.

Note: When creating a new location, the following sub-location is automatically created: <Location Name> - Other.
This sub-location refers to all the addresses that are not specified in the custom sub-locations). This sub-location is reserved and cannot be deleted.

Request Details:

  • Request URL: “admin-api.axissecurity.com/api/v1/locations”
  • Request Method: POST
  • Request Headers: Authorization: “Bearer {API Token}”
  • Request Body (JSON):
FieldTypeDescription
NameMandatoryThe location name

📘

NOTE

  • The ID parameter is NOT required when adding a new location via the API
  • Creating a new location creates a reserved sub-location "Other"

Request Format:

{
"name":"Chicago Office",
}

Successful Response Format: 

{
"id":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
"name":"Chicago Office",
"subLocations":
  [
    {
      "id":"ee472846-8e02-4377-977e-292dd56913d0",
      "name":"Chicago Office - Other"
    }
  ],
"tunnels": []
}

Response Codes:

CodeDescription
201Location created successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
409Conflict - Location already exists with the same name
500Internal server error

Get the details of an existing location

To get the details of an existing location, the location ID should be added to the request URL.

Request Details:

  • Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>”
  • Request Method: GET
  • Request Headers: Authorization: “Bearer {API Token}”
  • Request Body: empty

Successful Response Format:

{
"id":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
"name":"Chicago Office",
"subLocations":
  [
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "name":"Chicago Office - VLAN0001"
    },
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "name":"Chicago Office - VLAN0002"
    },
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "name":"Chicago Office - Guest-Wifi"
    },
    {
      "id":"ee472846-8e02-4377-977e-292dd56913d0",
      "name":"Chicago Office - Other"
    }
  ],
"tunnels":
  [
    {
      "id":"6ee0bd21-4f50-454a-9f75-82f6933d54b0",
      "name":"Chicago IPSec1"
    }
  ]
}

Response Codes:

CodeDescription
200Location information retrieved successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404Location not found
500Internal server error

Get a list of existing locations

Request Details:

  • Request URL: “admin-api.axissecurity.com/api/v1/locations?pageSize=100&pageNumber=1”
  • Request Method: GET
  • Request Headers: Authorization: “Bearer {API Token}”
  • Query params:
Query ParamDescription
PageSizeSpecify the maximum number of tags to retrieve.
PageNumberPage number 1 will retrieve the first tags.

Successful Response Format:

{
"pageNumber":1,
"pageSize":100,
"firstPage":"<URL to retrieve first page>",
"lastPage":"<URL to retrieve last page>",
"totalPages":1,
"totalRecords":50,
"nextPage":"<URL to retrieve next page>",
"previousPage":"<URL to retrieve previous page>",
"data":[
    {
    "id":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
    "name":"Chicago Office",
    "subLocations":
      [
        {
          "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
          "name":"Chicago Office - VLAN0001"
        },
        {
          "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
          "name":"Chicago - VLAN0002"
        },
        {
          "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
          "name":"Chicago - Guest-Wifi"
        },
        {
          "id":"ee472846-8e02-4377-977e-292dd56913d0",
          "name":"Chicago - Other"
        }
      ],
    "tunnels":
      [
        {
          "id":"6ee0bd21-4f50-454a-9f75-82f6933d54b0",
          "name":"Chicago IPSec1"
        }
      ]
    }
  ]
}

Response Codes:

CodeDescription
200Location retrieved successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
500Internal server error

Update an existing location

To update an existing location, the location's ID should be added to the request URL.
A successful response will return a 204 response with the location details.

Request Details::
Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>”
Request Method: PUT
Request Headers: Authorization: “Bearer {API Token}”

Request Format: 

{
	"name":"<new location name>",
}

Successful Response Format: 

{
  "id":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
  "name":"<new location name>",
  "subLocations":
  [
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "name":"Chicago Office - VLAN0001"
    },
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "name":"Chicago Office - VLAN0002"
    },
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "name":"Chicago Office - Guest-Wifi"
    },
    {
      "id":"ee472846-8e02-4377-977e-292dd56913d0",
      "name":"<new location name> - Other"
    }
  ],
  "tunnels":
  [
    {
      "id":"6ee0bd21-4f50-454a-9f75-82f6933d54b0",
      "name":"Chicago IPSec1"
    }
  ]
}

Response Codes:

CodeDescription
204Location updated successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404Location not found
500Internal server error

Delete a location

To delete an existing location, the location's ID should be added to the request URL.
A successful response will return a 204 response with an empty body.

Request Details:

  • Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>”
  • Request Method: Delete
  • Request Headers: Authorization: “Bearer {API Token}”
  • Request Body: empty

Response Codes:

CodeDescription
204Location deleted successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
403Operation is Forbidden. Make sure the location is not used by any tunnel or policy rule.
404Location not found
500Internal server error

Sub-Locations

Add a new sub-location to a location

The management API allows administrators to create new sub location.

Request Details:

  • Request URL: “admin-api.axissecurity.com/api/v1/locations/{location ID}/sublocations”
  • Request Method: POST
  • Request Headers: Authorization: “Bearer {API Token}”
  • Request Body (JSON):
FieldTypeDescription
NameMandatoryThe location name
IpRangesMandatoryList of IP addresses, IP ranges and CIDRs

📘

NOTE

The ID parameter is NOT required when adding a new sub location via the API

Request Format:

{
"name":"Chicago Office - VLAN0003",
"ipRanges": ["10.10.3.0/24"]
}

Successful Response Format: 

{
"id":"335518d8-d48a-4039-ab88-a90e9f6d828a",
"locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
"name":"Chicago Office - VLAN0003",
"type": "Custom",
"ipRanges": ["10.10.3.0/24"]
}

Response Codes:

CodeDescription
201Location created successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
409Conflict - Sub-location already exists with the same name in the location
500Internal server error

Get the details of an existing sub-location in a location

To get the details of an existing sub-location, the location ID and the sub-location ID should be added to the request URL.

Request Details:

  • Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>”/sublocations/<sub-location ID>”
  • Request Method: GET
  • Request Headers: Authorization: “Bearer {API Token}”
  • Request Body: empty

Successful Response Format (Custom Sub-Location):

{
"id":"335518d8-d48a-4039-ab88-a90e9f6d828a",
"locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
"name":"Chicago Office - VLAN0003",
"type": "Custom",
"ipRanges": ["10.10.3.0/24"]
}

Successful Response Format (Other Sub-Location):

{
"id":"ee472846-8e02-4377-977e-292dd56913d0",
"locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
"name":"Chicago Office - Other",
"type": "Other",
"ipRanges": []
}

Response Codes:

CodeDescription
200Sub-Location information retrieved successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404Sub-Location not found
500Internal server error

List existing sub-locations in a location

Request Details:

  • Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>/sublocations/?pageSize=100&pageNumber=1”
  • Request Method: GET
  • Request Headers: Authorization: “Bearer {API Token}”
  • Query params:
Query ParamDescription
PageSizeSpecify the maximum number of tags to retrieve.
PageNumberPage number 1 will retrieve the first tags.

Successful Response Format:

{
"pageNumber":1,
"pageSize":100,
"firstPage":"<URL to retrieve first page>",
"lastPage":"<URL to retrieve last page>",
"totalPages":1,
"totalRecords":50,
"nextPage":"<URL to retrieve next page>",
"previousPage":"<URL to retrieve previous page>",
"data":[
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
      "name":"Chicago Office - VLAN0001",
      "type": "Custom",
      "ipRanges": ["10.10.1.0/24"]
    },
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
      "name":"Chicago Office - VLAN0002",
      "type": "Custom",
      "ipRanges": ["10.10.2.0/24"]
    },
    {
      "id":"335518d8-d48a-4039-ab88-a90e9f6d828a",
      "locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
      "name":"Chicago Office - VLAN0003",
      "type": "Custom",
      "ipRanges": ["10.10.3.0/24"]
  	},
    {
      "id":"e15ac0bc-a716-4f98-9b48-346c3c1f04f9",
      "locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
      "name":"Chicago Office - Guest-Wifi",
      "type": "Custom",
      "ipRanges": ["192.168.1.0/24","192.168.12.22"]
    },
    {
      "id":"ee472846-8e02-4377-977e-292dd56913d0",
      "locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
      "name":"Chicago Office - Other",
      "type": "Other",
      "ipRanges": []
    }
  ]
}

Response Codes:

CodeDescription
200Location retrieved successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
500Internal server error

Update an existing sub-location in a location

To update an existing location, the location's ID and the sub-location's ID should be added to the request URL.
A successful response will return a 204 response with the location details.

Request Details:

  • Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>/<sub location ID>”
  • Request Method: POST
  • Request Headers: Authorization: “Bearer {API Token}”

Request Format: 

{
"name":"<new sub-location name>",
"ipRanges": ["<new ip range>"]
}

Successful Response Format: 

{
"id":"335518d8-d48a-4039-ab88-a90e9f6d828a",
"locationID":"d88fc23a-59a1-476a-a62e-a51ff3543fe7",
"name":"<new sub-location name>",
"type": "Custom",
"ipRanges": ["<new ip range>"]
}

Response Codes:

CodeDescription
204Location updated successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
404Location not found
409Conflict - Sub-location already exists with the same name in the location
500Internal server error

Delete an existing sub-location in a location

To delete an existing location, the location's ID should be added to the request URL.
A successful response will return a 204 response with an empty body.

Note: The auto-created sub-location, <Location Name> - Other, is reserved and cannot be deleted.

Request Details:

  • Request URL: “admin-api.axissecurity.com/api/v1/locations/<location ID>/sublocations/<sub-location ID>”
  • Request Method: Delete
  • Request Headers: Authorization: “Bearer {API Token}”
  • Request Body: empty

Response Codes:

CodeDescription
204Location deleted successfully
400Bad request
401Unauthorized access. Make sure the API token includes writing permissions. Click here for more information.
403Operation is Forbidden. Make sure the sub-location is not of type "Default" or "Other", and it's not used by any policy rule.
404Location not found
500Internal server error

Updated about 1 year ago

Copyright © 2021 Axis Security. All rights reserved.