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 Authentication: Getting Started to obtain your credentials for accessing 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 sites, persons, person groups, doors, and door groups.

To retrieve the ID of the organization attached to your application, navigate to the application you created and copy the org ID.

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

The API response contains the organization ID, name, etc.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "e222648c-48bb-4dbe-9d46-7c2484fad1bd",
  "name": "Proxy",
  "mainLocation": {
    "address": "15th Street San Francisco",
    "coordinates": {
      "lat": 37.8269775,
      "lng": -122.4229555
    }
  },
  "brandColor": "#FA3350",
  "createdAt": "2019-08-30T09:42:30.454Z",
  "updatedAt": "2019-08-30T09:42:30.454Z"
}

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

2Step 2: Create a new site

A Site is a collection of people and doors where you get an overview of a specific area within your company. It could be devisions between floors in a large office-building or different office-locations such as Proxy SF or Proxy NY. Sites are required to create access policies.

notice-information

Replace the org ID e222648c... below with your org ID.


1
2
3
4
5
6
7
8
9
10
curl -X POST \
    https://api.proxy.com/manage/sites \
    -u '{App-Key}:{App-Secret}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    --data '{
        "orgId": "e222648c-48bb-4dbe-9d46-7c2484fad1bd",
        "name": "My first Site",
        "timeZone": "America/Los_Angeles"
    }'

The API response contains the site ID, name and some details:

1
2
3
4
5
6
7
8
9
{
    "id": "9caf6139-49b4-4a87-84d8-5913beea8bb6",
    "tag": "site:my-first-site",
    "name": "My first Site",
    "details": { },
    "timeZone": "America/Los_Angeles",
    "createdAt": "2019-08-30T09:42:30.454Z",
    "updatedAt": "2019-08-30T09:42:30.454Z"
}

For additional details, see the Create a site API reference.

3Step 3: Create a new person group

Person groups collect a number of persons (members) in your organization. Once a group is created, you can add it to access policies that give access. Groups can be global (available for all sites in an organization) or attached to a specific site.

1
2
3
4
5
6
7
8
curl -X POST \
    https://api.proxy.com/manage/groups/?type=persons \
    -u '{App-Key}:{App-Secret}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    --data '{
        "name": "My First Group"
    }'

The API response contains the group ID, name and some details:

1
2
3
4
5
6
7
8
9
10
{
    "id": "1fef6088-061d-40c5-80de-96e956c33337",
    "name": "Engineers",
    "details": {},
    "isGlobal": true,
    "tag": "person-group:my-first-group",
    "type": "persons",
    "createdAt": "2020-09-25T09:42:30.454Z",
    "updatedAt": "2020-09-25T09:42:30.454Z"
}

For additional details, see the Create a person group API reference.

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

notice-information

Replace the group tag person-group:my-first-group with the group tag from the create a person group step.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -X POST \
    https://api.proxy.com/manage/persons/import \
    -u '{App-Key}:{App-Secret}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    --data '{
        "tags": ["person-group:my-first-group"],
        "items": [
            {
                "email": "jenny@example.com",
                "name": "Jenna Jocobs"
            }
        ]
    }'

For additional details, see the Create multiple persons API reference.

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 (enable by passing the sendInvite flag, see the API reference), it adds them to the group or groups you specify.

If you are in need of setting credentials, check Proxy Mobile Access API Reference for details about supported credential formats and methods.

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

5Step 5: Create an access policy for your group

Access policies are set between groups of people and doors (a door is connected to a device, and a device could, for example, be a reader or a sensor) managed by your organization. Normally, these doors are automatically added to your list of devices when they are provisioned during install.

We will retrieve the list of doors in your organization.

notice-error

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


1
2
3
4
5
curl -X GET \
    https://api.proxy.com/manage/doors \
    -u '{App-Key}:{App-Secret}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "totalCount": 1,
  "items": [
    {
      "id": "0caf6139-49b4-4a87-84d8-5913beea8bb6",
      "name": "Example Front Door",
      "details": {},
      "tag": "door:example-front-door",
      "tags": [],
      "syncStatus": "active",
      "createdAt": "2019-08-30T09:42:30.454Z",
      "updatedAt": "2019-08-30T09:42:30.454Z"
    }
  ]
}

For additional details, see the Retrieve all doors API reference.

Now we are ready to create an access policy that grants all persons of our person group access to this particular door:

notice-information

Replace the site ID 9caf6139..., person group ID 1fef6088..., and the door ID 0caf6139..., with the site ID, person group ID, and door ID, respectively from the previous steps.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
curl -X POST \
    https://api.proxy.com/manage/policies?siteId=9caf6139-49b4-4a87-84d8-5913beea8bb6 \
    -u '{App-Key}:{App-Secret}' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    --data '{
      "name":"Engineering",
      "active":true,
      "document":{
          "Version":"2019-05-24",
          "Statement":{
            "Effect":"Allow",
            "Action":[
                "unlock"
            ],
            "Grant":[
                "proxy:person-group:1fef6088-061d-40c5-80de-96e956c33337"
            ],
            "Resource":[
                "proxy:door:0caf6139-49b4-4a87-84d8-5913beea8bb6"
            ],
            "Ruleset":{
                "mode":"tap-in",
                "schedule":[
                  
                ]
            }
          }
      }
    }'

For additional details, see the Create a policy API reference.