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.

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:

Id · 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": "[e-mail]",
    "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:

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.

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

1. Build the Access Groups endpoint

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

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

3. Configure Nexudus

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

4. Map access groups

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

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