📘
API v1 and v2 are NOT deprecated, and will continue to work as usual.

URL

A typical endpoint in API v1 looks like this: https://<tenant>.armis.com/api/v1/<endpoint>.

In API v3 it's https://api.armis.com/v3/<endpoint>.

You'll notice that in v3 the <tenant> is missing - that's because we have this information either in the body of the request (when authenticating) or in the headers of the request (when making calls).

Authentication

In both methods of authentication (v1 and v3) you have a long-lived secret key, which you exchange for a short-lived token for making calls.

However, while in v1 the mechanism is proprietary, in v3 uses OAuth2 with the client_credentials flow.

For more details, please read the Authentication guide.

Permissions

In v1, the generated access token has all of the permissions that the user that created the secret key has.

In v3, you have to specify which permissions you want the access token to have, out of what's available to the user that created the token. This allows for a more secure data exchange.

Endpoints

Here's a breakdown of v1 endpoints with v3 equivalent:

Authentication

v1 endpoint	v3 equivalent
`POST /api/v1/access_token/`	`POST /v3/oauth/token`

Custom Properties

v1 endpoint	v3 equivalent
`POST /api/v1/devices/_bulk/`	`POST /v3/assets/_bulk`
`GET /api/v1/device-custom-property-configurations/`	`GET /v3/settings/device-custom-properties`

System Reports

v1 endpoint	v3 equivalent
`POST /api/v1/reports/`	`PATCH /v3/data-export/{entity}`
`PATCH /api/v1/reports/{report_id}/`	`PATCH /v3/data-export/{entity}`
`GET /api/v1/report-results/{report_id}/`	`/v3/data-export/{entity}`

Sites

v1 endpoint	v3 equivalent
`GET /api/v1/sites/`	`GET /v3/settings/sites`
`POST /api/v1/sites/`	`POST /v3/settings/sites`
`GET /api/v1/sites/site_id/`	`GET /v3/settings/sites/{site_id}`
`PATCH /api/v1/sites/site_id/`	`PATCH /v3/settings/sites/{site_id}`
`DELETE /api/v1/sites/site_id/`	`DELETE /v3/settings/sites/{site_id}`

Devices

v1 endpoint	v3 equivalent
`POST /api/v1/devices/`	`POST /v3/assets/_search`

There are dozens of other endpoints in API v1 that don't have an equivalent in API v3 as of yet. If you're missing a specific capability, please let us know in the community.