> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Access Control API

> Integrate your own access control system with Nexudus using the Generic Access Control API.

The Custom Access Control API allows system integrators to connect any access control system to Nexudus. Instead of relying on a pre-built integration, you provide your own endpoints and Nexudus communicates with them to manage access groups and notify your system of changes.

## How it works

Nexudus maintains a mapping table that links resources, day passes, and floor plan items to access groups in your system. When a customer books a resource, purchases a day pass, or is assigned a desk through a contract, Nexudus determines which access groups they should belong to and notifies your system via a webhook.

The integration requires two components:

1. **Access Groups endpoint** — An endpoint you host that returns the list of access groups in your system. Nexudus calls this endpoint so operators can map Nexudus items to your access groups from the admin panel.
2. **Webhook receiver** — An endpoint you host that receives notifications from Nexudus whenever a customer's access groups change.

## Configuration

Configure the integration from the Nexudus admin panel at **Settings > Integrations > Custom ACS**:

| Field                              | Description                                                                         |
| ---------------------------------- | ----------------------------------------------------------------------------------- |
| **Access groups API endpoint**     | The URL of your endpoint that returns the list of access groups.                    |
| **Access groups API Access Token** | An optional bearer token Nexudus includes when calling your access groups endpoint. |
| **Webhook URL**                    | The HTTPS URL Nexudus calls to notify your system of access changes.                |
| **Webhook Bearer**                 | The bearer token Nexudus includes in webhook requests to your endpoint.             |

<Warning>
  The webhook URL must use HTTPS. Nexudus does not send webhook notifications to HTTP endpoints.
</Warning>

## Access Groups endpoint

You must provide an endpoint that returns the list of access groups available in your system. Nexudus calls this endpoint when an operator opens the access control configuration page in the admin panel.

### Request

Nexudus sends a `GET` request to your endpoint with the following headers:

| Header                        | Description                                                         |
| ----------------------------- | ------------------------------------------------------------------- |
| `Authorization`               | `Bearer <token>` — Included only if you configured an Access Token. |
| `X-Nexudus-Business-UniqueId` | The unique identifier of the Nexudus Location making the request.   |
| `X-Nexudus-User-UniqueId`     | The unique identifier of the admin user performing the action.      |

### Response

Your endpoint must return a JSON array of access group objects:

```json theme={null}
[
  {
    "Id": "group-1",
    "Name": "Main Entrance"
  },
  {
    "Id": "group-2",
    "Name": "Meeting Rooms"
  },
  {
    "Id": "group-3",
    "Name": "Executive Floor"
  }
]
```

Each object has two fields:

<ResponseField name="Id" type="string" required>
  A unique identifier for the access group in your system.
</ResponseField>

<ResponseField name="Name" type="string" required>
  A human-readable name displayed to operators in the Nexudus admin panel.
</ResponseField>

<Note>
  Nexudus enforces a 10-second timeout when calling your access groups endpoint. Make sure your endpoint responds within this limit.
</Note>

## Mapping access groups

Once Nexudus retrieves the list of access groups from your endpoint, operators can map them to Nexudus items from the admin panel. The following item types can be mapped:

* **Resources** — Bookable inventory such as meeting rooms, phone booths, and event spaces.
* **Day passes** — Time-limited passes that grant access to the Location.
* **Floor plan desks** — Desks assigned through contracts on a floor plan.

Each item can be assigned to one or more access groups. When a customer acquires one of these items, they are added to the corresponding access groups.

## Webhook notifications

Whenever a customer's access groups change, Nexudus sends a webhook notification to the URL you configured. Changes are triggered by:

* A customer purchasing or being assigned a day pass.
* A customer making or being added as a visitor to a resource booking (within 15 minutes of the booking start time).
* A customer's contract including assigned desks.
* A customer's day pass expiring or being revoked.
* A booking ending.
* A customer being deactivated.
* A customer checking in with a day pass.
* A team leader's contract desks being inherited by team members.

### Request

Nexudus sends a `POST` request to your webhook URL with the following headers:

| Header          | Description                                                  |
| --------------- | ------------------------------------------------------------ |
| `Authorization` | `Bearer <webhook_bearer>` — The bearer token you configured. |

### Payload

The webhook payload contains the customer's current access state:

```json theme={null}
{
  "time": "2025-01-15T10:30:00Z",
  "business": {
    "id": 123456,
    "name": "My Coworking Space",
    "uniqueId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "coworker": {
    "id": 789012,
    "full_name": "Jane Smith",
    "email": "jane@example.com",
    "uniqueId": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
    "accessCardId": "CARD-001",
    "keyFobNumber": "FOB-123",
    "accessPincode": "1234"
  },
  "access_signature": "hash-of-current-access-state",
  "groups": ["group-1", "group-2"],
  "schedule": [
    {
      "group": "group-1",
      "expires_on": null
    },
    {
      "group": "group-2",
      "expires_on": "2025-01-15T12:00:00Z"
    }
  ]
}
```

<Accordion title="Payload field reference">
  | Field                    | Type             | Description                                                                                        |
  | ------------------------ | ---------------- | -------------------------------------------------------------------------------------------------- |
  | `time`                   | `string`         | ISO 8601 timestamp of when the notification was generated (UTC).                                   |
  | `business.id`            | `number`         | The Nexudus Location ID.                                                                           |
  | `business.name`          | `string`         | The name of the Location.                                                                          |
  | `business.uniqueId`      | `string`         | The unique identifier of the Location.                                                             |
  | `coworker.id`            | `number`         | The customer's Nexudus ID.                                                                         |
  | `coworker.full_name`     | `string`         | The customer's full name.                                                                          |
  | `coworker.email`         | `string`         | The customer's email address.                                                                      |
  | `coworker.uniqueId`      | `string`         | The customer's unique identifier.                                                                  |
  | `coworker.accessCardId`  | `string`         | The customer's access card identifier, if set.                                                     |
  | `coworker.keyFobNumber`  | `string`         | The customer's key fob number, if set.                                                             |
  | `coworker.accessPincode` | `string`         | The customer's access PIN code, if set.                                                            |
  | `access_signature`       | `string`         | A hash representing the customer's current access state.                                           |
  | `groups`                 | `string[]`       | The list of access group IDs the customer currently belongs to.                                    |
  | `schedule`               | `object[]`       | Detailed schedule showing each group and when access expires.                                      |
  | `schedule[].group`       | `string`         | The access group ID.                                                                               |
  | `schedule[].expires_on`  | `string \| null` | ISO 8601 expiration timestamp, or `null` if access does not expire (e.g. from an active contract). |
</Accordion>

### Access expiration rules

The `expires_on` field in the schedule varies depending on what grants access:

| Source                                               | Expiration                                                      |
| ---------------------------------------------------- | --------------------------------------------------------------- |
| Day pass                                             | The day pass expiration date, extended by 12 hours.             |
| Resource booking                                     | The booking end time.                                           |
| Desk in a contract                                   | `null` (no expiration while the contract is active).            |
| Team member inheriting from a team leader's contract | The contract renewal date, or `null` if no renewal date is set. |

When a customer belongs to a group through multiple sources (for example, a day pass and a booking), the latest expiration is used.

### Handling the webhook

Your webhook endpoint should:

1. **Respond with a `2xx` status code** to acknowledge receipt.
2. **Replace the customer's access groups** with the list provided in the `groups` array. This is a full replacement, not an incremental update.
3. **Use the `schedule` array** to set time-based access rules if your system supports them.

<Info>
  Nexudus sends a webhook notification on every access update, even if the customer's groups have not changed. Your system should handle idempotent updates gracefully.
</Info>

## Implementation checklist

<Steps>
  <Step title="Build the Access Groups endpoint">
    Create an HTTPS endpoint that returns a JSON array of `{"Id": "...", "Name": "..."}` objects representing your access groups.
  </Step>

  <Step title="Build the Webhook receiver">
    Create an HTTPS endpoint that accepts POST requests with the webhook payload described above and updates access in your system accordingly.
  </Step>

  <Step title="Configure Nexudus">
    In the Nexudus admin panel, navigate to **Settings > Integrations > Custom ACS** and enter your endpoint URLs and tokens.
  </Step>

  <Step title="Map access groups">
    Use the admin panel to map your access groups to Nexudus resources, day passes, and floor plan desks.
  </Step>

  <Step title="Test the integration">
    Assign a day pass to a test customer and verify that your webhook receives the expected notification with the correct access groups.
  </Step>
</Steps>