MAC Address Bypass (MAB) API
Overview
The Nile MAC Address Bypass (MAB) API allows you to programmatically retrieve network metadata (segments, sites, zones, etc.) and update a device’s MAC address authentication status. It can be used to build automated MAB approval workflows with third-party tools. MAB is most commonly applied to IoT, headless devices, or other clients that cannot support 802.1X authentication.
The MAC Address Bypass (MAB) API is offered as-is and is not included in Nile’s supported feature set. Please note that Nile Support does not offer troubleshooting or assistance for this API.
Authentication
All requests require an API key.
Header format:
Obtain your API key in the Nile portal.
Creating an API key
- Log into Nile Portal using an admin account.
- Click on the Global Settings icon on the left side
- Click on Security tab
- On API key management, click on the “ADD KEY” button to generate a new API token.
- Fill Add key info:
- Name: Key name (example “Nile MAB API”)
- Duration (days): token key validity, the maximum is 1 year (365 days)
- Workflow: Select the workflow that we want to generate a key for. For MAB Onboarding, we select: ‘MAB Onboarding API’
- Read only: Select ‘Read-only’ to enable the API for read-only access. By default, the API key permits read/write operations. However, if you intend to update MAB entries, such as approving or denying MAC addresses in specific segments, it is advised not to enable 'Read-only' access."Click on SAVE to save the config.
- Click Save to save the API key.
After saving the configuration, a JSON file containing key information will automatically download to your computer.
🔒 NOTE: Please keep this information in a secure location. For security reasons, this file cannot be downloaded again. If the key is lost or compromised, it must be revoked, and a new key must be created.
Quick Start
Step 1. Export your API key:
2. List available segments
Note on formatting: By default, curl prints JSON as one long line. For readability, pipe through jq:
If jq is not installed:
- macOS: brew install jq
- Debian/Ubuntu: sudo apt-get install jq
- Windows PowerShell: ... | ConvertFrom-Json | ConvertTo-Json -Depth 8
Sample output (pretty-printed with jq, truncated)
3. Get client-config for a device (by MAC address)
Sample output (truncated, pretty-printed with jq, anonymized)
Endpoints
For readability, long IDs are truncated with .... In real responses you will see full UUID values.
Segments
Retrieve tenant segments.
Sample output (truncated)
Sites
Retrieve site information.
Sample output (truncated)
Buildings
Retrieve buildings.
Sample output (truncated)
Floors
Retrieve floors.
Sample output (truncated)
Zones
Retrieve zones.
Sample output (truncated)
Client Configs — List
Returns JSON data that includes a list of (device) client configurations within a given tenant. Multiple attributes can be used for filtering, including:
- tenantId
- macAddress
- lockToPort
- Geo Scope IDs (e.g., site_id, building_id, floor_id, etc.)
Sample execution and output (truncated)
Client Configs — Update
Use this endpoint to update a device’s MAC address authentication state.
Required fields (per MAC)
- id — the full ID returned by client-configs-list (tenant + MAC)
- macAddress — the device’s MAC address
- segmentId — the ID of the segment to assign
- state — new state value
- description — optional free text note
Valid state values
State | Meaning | Typical use |
|---|---|---|
AUTH_OK | Device approved | Approve IoT/headless |
AUTH_DENIED | Device denied access | Block rogue or unwanted |
WAITING_FOR_APPROVAL (if shown) | Pending admin action | Default for new devices |
Single-device example
Create mac.json:
Run the PATCH:
Bulk update (multiple devices)
You can update more than one MAC in a single request by adding multiple objects to the macsList array.
Response codes
- 204 No Content → update succeeded (most common)
- Errors return JSON body with code and message
Best practices
- Always GET the device first using client-configs-list to confirm the id and segmentId before PATCHing.
- Use a JSON file (-d @mac.json) rather than inline JSON to avoid quoting issues.
Example Scripts
#!/usr/bin/env python3
# Usage: export NILE_API_KEY=... python3 mab_approve.py <macAddress> <segmentId>
import os, sys, json, requests
BASE_URL = "https://u1.nile-global.cloud/api/v1"
API_KEY = os.environ.get("NILE_API_KEY")
if not API_KEY:
sys.stderr.write("❌ Missing NILE_API_KEY environment variable\n")
sys.exit(1)
def h():
return {
"Authorization": f"Bearer {API_KEY}",
"Accept": "application/json",
"Content-Type": "application/json",
}
def get_client_config(mac: str):
url = f"{BASE_URL}/client-configs-list?filter=macAddress=={mac}"
r = requests.get(url, headers=h(), timeout=30)
r.raise_for_status()
data = r.json()
if isinstance(data, list):
return data[0] if data else None
if isinstance(data, dict) and isinstance(data.get("data"), list):
return data["data"][0] if data["data"] else None
return None
def approve_mac(cfg_id: str, mac: str, segment_id: str):
body = {
"macsList": [
{"id": cfg_id, "macAddress": mac, "segmentId": segment_id, "state": "AUTH_OK"}
]
}
r = requests.patch(f"{BASE_URL}/client-configs", headers=h(), json=body, timeout=30)
if r.status_code not in (200, 204):
raise RuntimeError(f"PATCH failed ({r.status_code}): {r.text}")
def main():
if len(sys.argv) != 3:
sys.stderr.write("Usage: NILE_API_KEY=... python3 mab_approve.py <macAddress> <segmentId>\n")
sys.exit(1)
mac, segment_id = sys.argv[1], sys.argv[2]
row = get_client_config(mac)
if not row:
sys.stderr.write(f"❌ No client-config found for MAC {mac}\n")
sys.exit(1)
# normalize possible shapes
cfg = row.get("clientConfig") or row.get("attributes") or row
cfg_id = cfg.get("id")
if not cfg_id:
sys.stderr.write("❌ Missing id in client-config response\n")
sys.exit(1)
approve_mac(cfg_id, mac, segment_id)
print(f"✅ Approved {mac} (id={cfg_id}) into segment {segment_id}")
if __name__ == "__main__":
main()