Using the 12Port API

12Port Horizon comes with a robust REST API library that can be used to efficiently manage a 12Port instance and its objects, automate operational functionality and create custom integrations with third party software and services. When considering the capabilities of the API, anything you can accomplish with your mouse and keyboard in the application's web GUI can also be achieved through one or more API calls. This is because the application's graphical user interface (GUI) relies on the same APIs that are available to you, making the potential for automation and integration virtually limitless.

Getting Started

When you are ready to start using the API, there are only two requirements:

an API token and
the necessary permissions to perform the function.

An API Token, associated to a named user account in the software, is used to authenticate the call to the application. If you do not currently possess an API token, speak with your 12Port Administrator or API Token Manager for assistance. They have the ability to generate a tenant or space limited token that can be used with the API.

Once authenticated using the API token, a further requirement is the necessary permission to perform this function. For example, if you want to use the API to create an asset in a container, then the user account associated with this API token must have permission to create an asset in this container, otherwise you should expect that the API call with fail with a 401 (Unauthorized) or similar error. If you cannot perform the action in the web GUI, you should not expect to be able to do the same using the API.

Learning the API

Now that you have your API token and the required permission, it is time to learn how to use the API.

There are two recommended methods to first learning how the 12Port API functions:

Use your native browser's DevTools to monitor the 12Port network traffic
Use the available 12Port OpenAPI documentation.

Using DevTools

Since the application's web GUI uses the same API calls to operate, the first method to learn the API is to monitor this traffic. For example, if you want to create an asset in a container, you can first open your browser's DevTools (usually the F12 key), switch to its Network console and perform this operation in the 12Port GUI. The network console will display the API via the Request URL, Method and any necessary payloads and responses, that were used during the operation.

This is a good method to get started understanding which API calls are made and how they are built, but for more detailed explanations and examples, we recommend also using the OpenAPI documentation in the next section.

Using OpenAPI Documentation

For a more formal understanding of how API calls are constructed, including descriptions and available parameters, the Swagger OpenAPI documentation is where you want to spend your time learning. This documentation includes the complete list of API calls available, grouped by object type, and Try it out functionality. This will be your complete guide to the 12Port API.

To access the 12Port Swagger OpenAPI documentation, login to the 12Port web GUI, navigate to My Profile > About and click the API Documentation link on the bottom of this page. Alternatively, from your 12Port authenticated browser session, access the documentation directly from the URL: https://<your12Port.com:6443>/ztna/<tenant>/<space>/api-docs/index.html

From the documentation index page, you are now ready to explore the full depth of the 12Port API. Click through the object type grouping and narrow down to a specific API call that you would like to perform. This specific API listing will provide the information and parameters to successfully execute this call, including the method, call, parameters, request body and potential responses.

If you want to use the Try it out function will testing, you first need to properly authenticate from the API documentation. To do this:

From the top of the index.html page of this documentation, enter your Tenant into the Server Variables section. For example, if wish to use a tenant named APITesting, then enter APITesting/root into this Tenant parameter.
Click the Authorize button to the right of this Tenant parameter, enter your valid API token for this tenant into the JWT Value field and finally, click the Authorize button. Click the Close button to continue.
Return to the API call that you want to test, enter any required parameters where appropriate and use the Try it out button, followed by the Execute button, to test the call.

After the call is executed, the Responses section below will provide any server responses received. This includes the Curl command, the Request URL and the Server response. The server response code is used to determine the success of the call, where:

Code 200 indicates a success message response
Code 401 indicates an unauthorized response which could mean that either your API token is not valid or lacks the required permission in this tenant or space to perform this operation
Code 404 indicates that the function does not exist
Code 500 indicates a server error executing this API function. Review the application's server logs for more details.

Using the API Outside of 12Port

Eventually, you will want to make these API calls from an application that is not 12Port to support automation or integration services. This can be done simply by using your API token and the Curl provided in the documentation (or written in your preferred language).

To use the Curl in a Linux or Mac Shell or Windows CMD:

Copy the complete script from the Curl parameter or use the copy to clipboard button to the right side of the field.
Open a new terminal (Linux or Mac) or cmd (Windows), paste and execute the script. If you are using a test instance with an untrusted or self-signed certificate, you may need to add the -k command-line option to the script to bypass the certificate check. Only use this command-line option for test or non-production script execution.
Review the response to determine the result.

Linux Terminal example

Windows CMD example

You can also create standalone scripts that can utilize variables for API token, URL and other values.

Linux Example (whoami)

Example whoami.sh script for Linux or Mac execution

#!/bin/sh

URL=https://localhost:6443/ztna/API/root
TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsInNpZyI6IjQ4ZWFmNDI0LWI0ZDMtNGYzMS05NDAxLTg3MzYxNGVhMmIwMyJ9.eyJuYmYiOjE3MjU0NzkxODM5MDgsImlzcyI6IiR7ZHluYW1pY30iLCJpYXQiOjE3MjU0NzkxODM5MDgsImp0aSI6IjBmMzdlN2NhLWQ5ZTUtNDk1Zi05NDM1LWZmYTBkZThlMDQzZSIsIm90eXAiOiJBUEkiLCJvdWlkIjoiZDFjNWYzNTAtNzg4NS00NjMwLWE3ZjMtOGU5NGY5NTA1ZDRiIiwib3VzciI6ImNocmlza2EiLCJvZGlyIjoiNjFmZDZjYTEtZTY1ZC00ZWE3LWEzYWYtZjk5ZjFjZjk1MDM4IiwiZXhwIjoxNzI2MzM0NjI1MDAwfQ.Pw7kqE8GevfaaHEduR8daprdMnntfVcNKbmv_WoKUPwkkmxXvCqBoeKAyy7O5AKSdSlR2d29tOreWDSDzBj4ug

curl -k -i "$URL/api/user/me" -H "Authorization: Bearer $TOKEN"

Windows Example (create Asset)

Example Windows CMD script to create a new Asset

curl -k -X POST "https://localhost:6443/ztna/API/root/api/asset/createAsset/c5154816-ae27-4574-9936-9854b64a548a/83ba342f-01fb-4fb6-b939-9fadd11c06ab" ^
-H "Content-type: application/json" ^
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsInNpZyI6IjQ4ZWFmNDI0LWI0ZDMtNGYzMS05NDAxLTg3MzYxNGVhMmIwMyJ9.eyJuYmYiOjE3MjU0NzkxODM5MDgsImlzcyI6IiR7ZHluYW1pY30iLCJpYXQiOjE3MjU0NzkxODM5MDgsImp0aSI6IjBmMzdlN2NhLWQ5ZTUtNDk1Zi05NDM1LWZmYTBkZThlMDQzZSIsIm90eXAiOiJBUEkiLCJvdWlkIjoiZDFjNWYzNTAtNzg4NS00NjMwLWE3ZjMtOGU5NGY5NTA1ZDRiIiwib3VzciI6ImNocmlza2EiLCJvZGlyIjoiNjFmZDZjYTEtZTY1ZC00ZWE3LWEzYWYtZjk5ZjFjZjk1MDM4IiwiZXhwIjoxNzI2MzM0NjI1MDAwfQ.Pw7kqE8GevfaaHEduR8daprdMnntfVcNKbmv_WoKUPwkkmxXvCqBoeKAyy7O5AKSdSlR2d29tOreWDSDzBj4ug" ^
--data "{\"name\": \"SQLProd-2785\",\"description\": \"Prod SQL Bos DC 85\",\"fields\": [{\"field\": {\"id\": \"5b64eacc-6b37-412d-bc2b-91dcb4834fe8\"},\"values\": [{\"stringValue\": \"bossqlprod2785.contoso.com\"}]},{\"field\": {\"id\": \"6d383ae7-e19e-4a32-848c-51e578a3b5ac\"},\"values\": [{\"stringValue\": \"bossqladmin\"}]},{\"field\": {\"id\": \"2cf76192-3ce1-4a67-b10a-ea8b9e6eb773\"},\"values\": [{\"stringValue\": \"FaUJneoxyKSbQEtG7W2ZDSch\"}]},{\"field\": {\"id\": \"15e33add-ce0e-46cd-8595-84bdb3e04b3d\"},\"values\": [{\"stringValue\": \"c51de9c7-2a1f-44fb-b268-e2b6bba9c5e8\"}]}]}"

Example Windows PowerShell script to create a new Asset

# Define the URI and headers
$uri = "https://localhost:6443/ztna/API/root/api/asset/createAsset/56347e30-6ff3-400c-8b93-1ef997c1457c/ce37c2a4-13d2-439b-aea4-5767886a5647"
$headers = @{
    "Content-type" = "application/json"
    "Authorization" = "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsInNpZyI6IjBjOTAzODc0LWM2MDEtNDkwZC05MDJmLTU0YzUxNzllMGJiZiJ9.eyJuYmYiOjE3MjY1MDE1MTU0NDgsImlzcyI6IiR7ZHluYW1pY30iLCJpYXQiOjE3MjY1MDE1MTU0NDgsImp0aSI6IjE5MjI3OWI0LTBhOTctNGM1Ni1hMjE4LTNmNzFjYWEwNGQ4MSIsIm90eXAiOiJBUEkiLCJvdWlkIjoiODUyYjg2Y2MtMWIzNy00ZDA3LWE0ZTAtYjg1N2ZiNTFiYTllIiwib3VzciI6ImNocmlzazEiLCJvZGlyIjoiNjFmZDZjYTEtZTY1ZC00ZWE3LWEzYWYtZjk5ZjFjZjk1MDM4IiwiZXhwIjoxNzI2OTMxNDA2MDAwfQ.ThmBQCnSmLp8INwJzvm3XoPPs-JZGSCtHJHzKl6c3qPGWNI6dTx7WsDZDLfIv9F-_JVQSExt15NjMVYyrsN2yg"
}

# Define the body content
$body = @{
    name = "SQLProd-2785"
    description = "Prod SQL Bos DC 85"
    fields = @(
        @{
            field = @{ id = "0fdb21c8-d4d1-40ee-b264-7a0b9034ea27" }
            values = @(@{ stringValue = "bossqlprod2785.contoso.com" })
        },
        @{
            field = @{ id = "483fa7ec-b3e2-49b6-beb9-61571f029d08" }
            values = @(@{ stringValue = "bossqladmin" })
        },
        @{
            field = @{ id = "a4611924-ae84-41cd-9951-842990f66fad" }
            values = @(@{ stringValue = "FaUJneoxyKSbQEtG7W2ZDSch" })
        },
        @{
            field = @{ id = "48d7c0f4-995d-43d3-90f6-014e5271ddd8" }
            values = @(@{ stringValue = "275c25fd-7bbe-4ff5-b4ec-e35a464c44e0" })
        }
    )
} | ConvertTo-Json -Compress -Depth 5

# Perform the POST request
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body -ContentType "application/json"

Tip

You must identify values based on the object's unqiue ID, not its name. For example, when defining an object like Parent Container, an Asset Field like Host or an Asset Tag, you must use this object's unique ID which can be obtained through the application's GUI or a separate API call.

Note

When the asset is created, the server response will be the unique ID of this new asset in the format {"value":"uniqueID"}.

Windows Example (create Container)

Example Windows CMD script to create a new Container

curl -k -X POST "https://localhost:6443/ztna/API/root/api/asset/createAsset/c5154816-ae27-4574-9936-9854b64a548a/dfb24ea0-0953-43a0-a23f-4e50d815e7a6" ^
-H "Content-type: application/json" ^
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsInNpZyI6IjQ4ZWFmNDI0LWI0ZDMtNGYzMS05NDAxLTg3MzYxNGVhMmIwMyJ9.eyJuYmYiOjE3MjU0NzkxODM5MDgsImlzcyI6IiR7ZHluYW1pY30iLCJpYXQiOjE3MjU0NzkxODM5MDgsImp0aSI6IjBmMzdlN2NhLWQ5ZTUtNDk1Zi05NDM1LWZmYTBkZThlMDQzZSIsIm90eXAiOiJBUEkiLCJvdWlkIjoiZDFjNWYzNTAtNzg4NS00NjMwLWE3ZjMtOGU5NGY5NTA1ZDRiIiwib3VzciI6ImNocmlza2EiLCJvZGlyIjoiNjFmZDZjYTEtZTY1ZC00ZWE3LWEzYWYtZjk5ZjFjZjk1MDM4IiwiZXhwIjoxNzI2MzM0NjI1MDAwfQ.Pw7kqE8GevfaaHEduR8daprdMnntfVcNKbmv_WoKUPwkkmxXvCqBoeKAyy7O5AKSdSlR2d29tOreWDSDzBj4ug" ^
--data "{\"name\": \"BOS SQL Servers\",\"description\": \"Contains all PROD SQL servers from BOS DC\"}"

Example Windows PowerShell script to create a new Container

# Define the URI and headers
$uri = "https://localhost:6443/ztna/API/root/api/asset/createAsset/56347e30-6ff3-400c-8b93-1ef997c1457c/f4ac60f6-3684-4396-9d4c-426850faed83"
$headers = @{
    "Content-type" = "application/json"
    "Authorization" = "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsInNpZyI6IjBjOTAzODc0LWM2MDEtNDkwZC05MDJmLTU0YzUxNzllMGJiZiJ9.eyJuYmYiOjE3MjY1MDE1MTU0NDgsImlzcyI6IiR7ZHluYW1pY30iLCJpYXQiOjE3MjY1MDE1MTU0NDgsImp0aSI6IjE5MjI3OWI0LTBhOTctNGM1Ni1hMjE4LTNmNzFjYWEwNGQ4MSIsIm90eXAiOiJBUEkiLCJvdWlkIjoiODUyYjg2Y2MtMWIzNy00ZDA3LWE0ZTAtYjg1N2ZiNTFiYTllIiwib3VzciI6ImNocmlzazEiLCJvZGlyIjoiNjFmZDZjYTEtZTY1ZC00ZWE3LWEzYWYtZjk5ZjFjZjk1MDM4IiwiZXhwIjoxNzI2OTMxNDA2MDAwfQ.ThmBQCnSmLp8INwJzvm3XoPPs-JZGSCtHJHzKl6c3qPGWNI6dTx7WsDZDLfIv9F-_JVQSExt15NjMVYyrsN2yg"
}

# Define the body content
$body = @{
    name = "BOS SQL Servers"
    description = "Contains all PROD SQL servers from BOS DC"
} | ConvertTo-Json -Compress

# Perform the POST request
Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body -ContentType "application/json"