Custom Access Control API - Nexudus Platform

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:

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.
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.

The webhook URL must use HTTPS. Nexudus does not send webhook notifications to HTTP endpoints.

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:

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

Each object has two fields:

string

required

A unique identifier for the access group in your system.

Name

string

required

A human-readable name displayed to operators in the Nexudus admin panel.

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

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:

{
  "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"
    }
  ]
}

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).

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:

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

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.

Implementation checklist

Build the Access Groups endpoint

Create an HTTPS endpoint that returns a JSON array of {"Id": "...", "Name": "..."} objects representing your access groups.

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.

Configure Nexudus

In the Nexudus admin panel, navigate to Settings > Integrations > Custom ACS and enter your endpoint URLs and tokens.

Map access groups

Use the admin panel to map your access groups to Nexudus resources, day passes, and floor plan desks.

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.

Getting Started

​How it works

​Configuration

​Access Groups endpoint

​Request

​Response

​Mapping access groups

​Webhook notifications

​Request

​Payload

​Access expiration rules

​Handling the webhook

​Implementation checklist

How it works

Configuration

Access Groups endpoint

Request

Response

Mapping access groups

Webhook notifications

Request

Payload

Access expiration rules

Handling the webhook

Implementation checklist