API Reference

Authentication

The API uses OAuth 2.0 client-credentials flow. Exchange your client ID and secret at POST /oauth/token to receive a bearer token valid for 3600 seconds. Include the token in the Authorization header for all subsequent requests. Tokens are scoped to the permissions assigned to the API client in the console.

Core Endpoints

The API is organised around four resource groups: /sites (site configuration and status), /policies (YAML policy CRUD), /sessions (active and historical authentication sessions) and /logs (AnchorLog query and export). All endpoints accept and return JSON. Pagination uses cursor-based tokens in the Link header.

• GET /sites — list all sites with status and Edge connectivity
• POST /policies — create or update a YAML policy document
• GET /sessions?site=<id>&status=active — list active sessions with filtering
• GET /logs?source=fortigate&from=<ISO8601>&to=<ISO8601> — query logs by source and time range
• POST /guests/vouchers — generate guest voucher batch with quota and expiry
• DELETE /sessions/<id> — disconnect a session via RADIUS CoA

Webhooks

Register webhook endpoints in the console to receive real-time event notifications. Supported events include session.authenticated, session.disconnected, policy.violation, posture.failed and log.sealed. Payloads are signed with HMAC-SHA256 using a per-endpoint secret. Failed deliveries are retried with exponential back-off up to 24 hours.

Rate Limiting & Errors

The API enforces a rate limit of 600 requests per minute per API client. When exceeded, the server returns HTTP 429 with a Retry-After header. All error responses follow RFC 7807 Problem Details format with a type URI, human-readable title and detail field. Common codes: 401 (invalid or expired token), 403 (insufficient scope), 404 (resource not found), 422 (validation error).

Example Requests

Below are curl examples for common operations. Replace $TOKEN with your bearer token and $SITE with your site ID. Fetch active sessions: curl -H 'Authorization: Bearer $TOKEN' https://api.siperone.com/v1/sessions?site=$SITE&status=active. Create a voucher batch: curl -X POST -H 'Authorization: Bearer $TOKEN' -d '{"count":10,"duration":"4h","bandwidth":"50mbps"}' https://api.siperone.com/v1/guests/vouchers.