Physical Access

Before starting this chapter, make sure that you have gone through the Authentication guide and are set up with an Application Key and Application Secret.

Proxy provides multiple connectors to enable synchronization between Proxy and the access control system used at your site. Pre-built and managed connectors are available for S2 and C-Cure, among others. Information about Proxy solutions and supported access control systems is available on the Proxy Support page.

Getting started

This guide will get you started building your own synchronization with Proxy, if one of the managed connectors is not suitable.

Synchronizing your access control list

notice-information Before you begin, see [Authenticate with your application credentials](/authentication#authenticate-with-your-application-credentials) to obtain credentials to access the Proxy API. In all of the code examples below, replace `{App-Key}` with your Application Key and `{App-Secret}` with your Application Secret.

1Step 1: Retrieve your organization

When you create your first application, you will be asked to create an organization to attach to your application. Organizations hold lists of members, groups, and devices.

To retrieve the ID of the organization attached to your application, use the following request:

1
2
3
4
curl -X GET \
    https://api.proxy.com/v1/orgs \
    -u '{App-Key}:{App-Secret}' \
    -H 'Accept: application/json'

The API responds with the list of attached organizations:

1
2
3
4
5
6
7
8
9
10
{
    "items": [
        {
            "id": "e222648c-48bb-4dbe-9d46-7c2484fad1bd",
            "name": {
                "formatted": "My First Org"
            }
        }
    ]
}

Copy the value of the id field from the first organization for the following steps.

2Step 2: Create a new group

Groups connect fixtures (readers, sensors) and members in your organization. Once a group is created, access policies can be managed at the group level. We recommend that you create a group for each distinct access level you want to manage.

notice-information Replace the org ID `e222648c-48bb-4dbe-9d46-7c2484fad1bd` below with your org ID.

1
2
3
4
5
6
7
8
9
10
curl -X POST \
    https://api.proxy.com/v1/orgs/e222648c-48bb-4dbe-9d46-7c2484fad1bd/groups \
    -u '{App-Key}:{App-Secret}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    --data '{
        "name": {
            "formatted": "My First Group"
        }
    }'

The API response contains the group ID and name:

1
2
3
4
5
6
{
    "id": "0becf177-4835-4753-b2dd-5c663d696c78",
    "name": {
        "formatted": "My First Group"
    }
}

3Step 3: Invite people to your organization and add them to groups

notice-information Replace the org ID `e222648c-48bb-4dbe-9d46-7c2484fad1bd` below with your org ID, and the group ID `0becf177-4835-4753-b2dd-5c663d696c78` with the group ID from the previous step.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl -X POST \
    https://api.proxy.com/v1/orgs/e222648c-48bb-4dbe-9d46-7c2484fad1bd/members \
    -u '{App-Key}:{App-Secret}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    --data '{
        "items": [
            {
                "email": "jenny@example.com",
                "name": {
                    "givenName": "Jenna",
                    "familyName": "Jocobs"
                },
                "memberOfGroup": [ "0becf177-4835-4753-b2dd-5c663d696c78" ]
            }
        ]
    }'

This request does several things: it invites the person to your organization, including sending them an invitation email with a link to download the Proxy App, it adds them to the group or groups you specify, and optionally, populates a credential for them. Refer to the API Reference for details about supported credential formats.

You may specify multiple people in a single request, to allow for bulk upload or delta synchronization of changes, and you may repeat this call at any time to update your access control list.

4Step 4: Add an access policy for your group

Access policies are set between groups of people and fixtures, which are all physical devices (readers, sensors) managed by your organization. Normally, these devices are automatically added to your list of fixtures when they are provisioned during install.

We will retrieve the list of fixtures in your organization.

notice-error If you have not installed any devices yet, please install and provision a hardware device before proceeding.

notice-information Replace the org ID `e222648c-48bb-4dbe-9d46-7c2484fad1bd` below with your org ID.

1
2
3
4
5
curl -X GET \
    'https://api.proxy.com/v1/orgs/e222648c-48bb-4dbe-9d46-7c2484fad1bd/fixtures' \
    -u '{App-Key}:{App-Secret}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

The API response contains the list of installed fixtures, including their ID and name:

1
2
3
4
5
6
7
8
9
10
{
"items": [
    {
        "id": "decaaed0-3698-4a0c-8272-78428efaf1e8",
        "name": {
            "formatted": "Main Entrance"
        },
        ...
    }
]

Now we are ready to create an access policy that grants all members of our group access to this particular device:

notice-information Replace the fixture ID `decaaed0-3698-4a0c-8272-78428efaf1e8` below with the fixture ID from the previous step, and the group ID `0becf177-4835-4753-b2dd-5c663d696c78` with the group ID from step 2.

1
2
3
4
5
curl -X PUT \
    'https://api.proxy.com/v1/fixtures/decaaed0-3698-4a0c-8272-78428efaf1e8/allow/0becf177-4835-4753-b2dd-5c663d696c78' \
    -u '{App-Key}:{App-Secret}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'