Integrations

Pre-built integrations

Accessia has a range of pre-built integrations that allow you to connect your system to third-party directories, cameras, locks, and environmental data

Directory integrations

Import users, groups, and access control settings, and enable SSO with a directory integration. Accessia supports:

• Microsoft Entra ID

• Okta

Camera integrations

View video alongside door access control events. Accessia supports:

• Avigilon Alta

• Eagle Eye

• Rhombus

Lock integration

Accessia supports ASSA ABLOY Aperio locks for access control

Environmental sensor integration

Accessia supports Neat devices to get environmental data from rooms

Custom API integration

Custom API integrations allow third-party integrations to read data such as the configured users and groups on Accessia secured using Machine-to-Machine authentication

API integrations have the same permissions as a global Event Viewer Accessia user. If your integration requires higher level permissions, talk to your Accessia representative

How to set up API integrations

To set up a custom API integration:

1. Go to the Integrations tab

2. Under Available integrations, find the API Integration and click ‘Add’

3. Name the integration

4. Copy the following fields:

   • Integration ID

   • Authentication URL

   • Secret

Note that the Secret will only be shown once. You can generate a new Secret at any time, but doing so will invalidate the previous Secret

1. On the Accessia portal, click ‘Save’

2. Authenticate the custom API integration

3. Exchange your Identity token for your Access and Refresh tokens

4. Use your Access token and Bearer token authentication against Accessia’s API

Authenticate the custom API integration

Use the copied Integration ID, Authentication URL, and Secret to get Access and Refresh tokens that you can pass to Accessia

Here is the simplified flow:

You’ll need to sign an identity JWT on your side using the Secret provided during setup. The signing algorithm is HMAC with SHA-256 and should include the following fields:

• iat - Issued At Time - UTC timestamp of when this token was issued

• exp - Expiry - UTC timestamp for when this token is valid until. We recommend that this is a few minutes after the value of iat

• jti (optional) - JWT ID - Unique identifier for this Identity token

Note that the Secret is base64 url encoded and you’ll need to decode it before use

Example of how you would generate this Identity token in Python:

import jwt
import base64
import time
import uuid

# Here you populate the values given to you during setup
INTEGRATION_DATA = {
    "integrationId": "<integrationId>",
    "secret": "<urlSafeBase64Secret>",
    "authenticationUrl": "<authenticationUrlValue>"
}
# you will need to sign a simple JWT with the shared secret. This JWT will be used as an Identity token to confirm who is requesting the Access and Refresh tokens
IDENTITY_TOKEN = jwt.encode(
  {
    "iat" : int(time.time()),
    "exp" : int(time.time()) + 300, # 5 minutes after creation
    "jti" : str(uuid.uuid4())
  },
  base64.urlsafe_b64decode(INTEGRATION_DATA["secret"]),
  "HS256"
)

Exchange your Identity token for your Access and Refresh tokens

To exchange your Identity token for your Access and Refresh tokens, execute a POST request against the following URL:

**<authenticationUrlValue>/exchange/integration**

The body of this request should be JSON containing:

• “token” - Your Identity token

• “integrationId” - The custom Integration ID shared with you at setup

As a response you’ll get a JSON body containing:

• “accessToken” - JWT you can use to access Accessia APIs

• “refreshToken” - JWT you can use to obtain new Access tokens

• “expiresIn” - How long your Access token will be valid for in seconds (default 21600)

• “domain” - The domain of your Accessia deployment

• “accessiaApisUrl” - URL against which you can execute your requests

Example Python implementation:

import requests
# here we make the request to exchange an identity token for Access and refresh tokens
integrationExchangeResponse = requests.post(
  f"{INTEGRATION_DATA['authenticationUrl']}/exchange/integration",
  json={
      "token" : IDENTITY_TOKEN,
      "integrationId" : INTEGRATION_DATA["integrationId"]
  }
).json()
REFRESH_TOKEN = integrationExchangeResponse['refreshToken']
ACCESS_TOKEN_HEADER = f"Bearer {integrationExchangeResponse['accessToken']}"
ACCESSIA_APIS_URL = integrationExchangeResponse['accessiaApisUrl']

Use your Access token and Bearer token authentication against Accessia’s API

Now that you have your Access token you can use it in combination with Bearer token authentication against Accessia’s API

Example of how to get groups containing the word “Office” with your new token:

ACCESS_TOKEN_HEADER = f"Bearer {integrationExchangeResponse['accessToken']}"
groupResponse = requests.get(
  ACCESSIA_APIS_URL + "/groups",
  headers = { "Authorization" : ACCESS_TOKEN_HEADER},
  params = { "source" : "all", "filter" : "Office", "limit" : 25, "sortBy" : "name" }
)

To find the APIs currently available for your deployment, go to <your_domain>/api_schema.json where you’ll find an API spec. You can then load it in a tool such as Swagger for easy browsing

Example of deployment URL

https://example.cloud.accessia.com/api_schema.json

If you need to refresh your Access token or if you need multiple parallel Access tokens, you can execute a POST request against

**<authenticationUrlValue>/refresh**

with a JSON body of:

• “refreshToken” - Your Refresh token

This will return the following response:

• “accessToken” - JWT you can use to access Accessia APIs

• “expiresIn” - Seconds your Access token will be valid for. Tokens are valid for 21600 seconds (six hours) by default. Contact Accessia if you need a different duration

• “domain” - The domain of your Accessia deployment

• “accessiaApisUrl” - URL against which you can execute your requests

Example:

refreshResponse = requests.post(
  f"{INTEGRATION_DATA['authenticationUrl']}/refresh",
  json={
      "refreshToken" : REFRESH_TOKEN,
  }
).json()
NEW_ACCESS_TOKEN_HEADER = f"Bearer {refreshResponse['accessToken']}"