Skip to content

Getting started

Welcome to the documentation of the Armis Python SDK!

This website will provide you all the information you'll need to interact with the SDK.

Installation

Use your favourite package manager to install the SDK, for example: 

1
pip install armis_sdk

Usage

All interaction with the SDK happens through the ArmisSdk class. You'll need five things:

  1. Audience: The url of the tenant you want to interact with, including trailing slash (e.g. https://acme.armis.com/).
  2. Client ID: The email address of the user account within the tenant that was used to generate the Client Secret.
  3. Client Secret: The confidential credential generated by your customer within Armis, paired with the Client ID.
  4. Vendor ID: An identifier unique to your developer account or integration, obtained when you register on our developer portal.
  5. Scopes: The specific permissions required by your access token to interact with the desired API endpoints.

You can either provide these values using the environment variables ARMIS_AUDIENCE, ARMIS_CLIENT_ID, ARMIS_CLIENT_SECRET, ARMIS_VENDOR_ID, and ARMIS_CLIENT_ID: 

1
2
3
from armis_sdk import ArmisSdk

armis_sdk = ArmisSdk()

or by passing them explicitly: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from armis_sdk import ArmisSdk
from armis_sdk import ClientCredentials

credentials = ClientCredentials(
    audience="<audience>",
    client_id="<client_id>",
    client_secret="<client_secret>",
    vendor_id="<vendor_id>",
    scopes=["scope1", "scope2"],
)
armis_sdk = ArmisSdk(credentials=credentials)

Tip

If you're building an application that interacts with multiple tenants, you can populate only the ARMIS_VENDOR_ID and ARMIS_SCOPES environment variable and pass the audience, client_id and client_secret explicitly: 

1
2
3
4
5
6
7
8
9
from armis_sdk import ArmisSdk
from armis_sdk import ClientCredentials

credentials = ClientCredentials(
    audience="<audience>",
    client_id="<client_id>",
    client_secret="<client_secret>",
)
armis_sdk = ArmisSdk(credentials=credentials)

Entity clients

Once you have an instance of ArmisSdk, you can start interacting with the various clients. Each handles use-cases of a specific entity.

Info

Note that all functions in this SDK that eventually make HTTP requests are asynchronous.

However, for convenience, all public asynchronous functions can also be executed in a synchronous way.

For example, if you want to update a site's location: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import asyncio

from armis_sdk import ArmisSdk
from armis_sdk.entities.site import Site

armis_sdk = ArmisSdk()

async def main():
    site = Site(id=1, location="new location")
    await armis_sdk.sites.update(site)

asyncio.run(main())