API

SpherAAA exposes a REST API for automating common platform tasks, such as:

  • Modifying data within Collections
  • Generating EAP-TLS certificates (PEM/PKCS12) and delivering them by email
  • Calling PolicyLogic endpoints (Auth, Acct, CoA, DM, etc.)
  • Adding, updating, or deleting NAS entries
  • Retrieving authentication logs and active sessions
  • And more

Getting started

Click to Configuration > API Keys

  1. Create an API key.
  2. Assign scopes that match the required permissions.
  3. Request an access token and call the API using the authorization header.

Swagger UI documentation is available at https://cloud.spheralogic.com/api/apidoc.

API keys

Each API key is identified by a ClientID/ClientSecret pair and carries a set of scopes that determine what the key is allowed to do.

Field Description
ClientID Unique identifier for the key.
Scopes One or more scopes granted to the key (see Scopes).
Status Active or Disabled. A key without an expiration date remains Disabled until an expiration date is set.
Expires Expiration date, or never. The maximum validity period is controlled by the platform setting api_key_max_days.
Comment Free-text description of the key.

!!! warning When you use API keys in your applications, ensure that they are kept secure during both storage and transmission.

Scopes

Scopes follow the format splc_<resource>:<read|write>. A request needs the scope matching the resource it touches (read for GET requests, write for anything else), unless the token carries splc_api:full_access, which bypasses scope checks entirely.

Scope Grants
splc_api:full_access Full access to every endpoint, regardless of other scopes.
splc_pki:read / splc_pki:write Read / generate and manage EAP-TLS certificates.
splc_collections:read / splc_collections:write Read / modify Collections data.
splc_nas:read / splc_nas:write Read / manage NAS entries.
splc_reports:read / splc_reports:write Read authentication logs and active sessions.
splc_policy:read / splc_policy:write Execute PolicyLogic endpoints.

Authentication

The API uses the OAuth2 Client Credentials grant. Exchange a ClientID/ClientSecret pair for a short‑lived access token, then send that token with every API call.

Requesting a token

POST /api/token

Send the request form-encoded, either with client_id/client_secret as form fields, or as HTTP Basic credentials (Authorization: Basic base64(client_id:client_secret)). Form fields take precedence when both are present.

Parameter Description
grant_type Must be client_credentials.
client_id The API key's ClientID.
client_secret The API key's secret.
scope Space-separated list of requested scopes, e.g. splc_collections:read splc_nas:write. Must be a subset of the scopes granted to the key. 
curl -X POST "https://cloud.spheralogic.com/api/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<clientId>" \
  -d "client_secret=<clientSecret>" \
  -d "scope=splc_collections:read splc_nas:write"

Response:

{
  "access_token": "<token>",
  "token_header": "Authorization",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scopes": ["splc_collections:read", "splc_nas:write"]
}

token_header echoes the header name to use for subsequent requests (Authorization by default). expires_in is in seconds.

Calling the API

Send the token in the header named by token_header, using the Bearer scheme:

Authorization: Bearer <access_token>

curl -X GET "https://cloud.spheralogic.com/api/nas/list" \
  -H "Authorization: Bearer <access_token>"

Endpoints

All endpoints are served under the /api prefix. Full request/response schemas are available in the Swagger UI (/api/apidoc).

PKI (certificates)

Method Path Description
POST /api/pki/gen/ Generate an EAP-TLS client certificate. cert_type query param selects the output: pem, p12, or apple_mobileconfig.
GET /api/pki/status/expiring/{expireInDays} List certificates expiring within the given number of days.
GET /api/pki/status/{sn} Get the status of a certificate by serial number.
PUT /api/pki/status/{sn}/{action} Update a certificate's status. action is revoked or good.

Example body for POST /api/pki/gen/:

{
  "ct": "US",
  "st": "NY",
  "city": "NewYork",
  "o": "Company",
  "ou": "OrganisationUnit",
  "cn": "anonymous@company.com",
  "days": "365",
  "passphrase": "nopass",
  "comment": "EAP-TLS Client Cert",
  "email_send_as_file": false,
  "email_send_as_url": false,
  "ssid": "nossid",
  "str_payload": false,
  "url_ttl": 3600
}

Collections

Method Path Description
GET /api/collections/{collection}/ List entries in a collection (paged, with optional date-range filters).
GET /api/collections/{collection}/{key}/{value} Retrieve entries matching key/value.
POST /api/collections/{collection} Upsert an entry.
PUT /api/collections/{collection}/{key}/{value} Update the entry matching key/value.
DELETE /api/collections/{collection}/{key}/{value} Delete the entry matching key/value.

Example body for POST /api/collections/{collection}:

{
  "User-Name": "user",
  "User-Password": "password",
  "NAS-Port-Id": "1",
  "Calling-Station-Id": "00:01:02:03:04:05"
}

NAS

Method Path Description
GET /api/nas/list List all NAS entries.
GET /api/nas/{nasIpAddr} Retrieve a single NAS entry.
POST /api/nas/ Add a NAS entry.
DELETE /api/nas/{nasIpAddr} Delete a NAS entry.

Reports

Method Path Description
GET /api/reports/auth Retrieve authentication logs. Query params: start, end, page.
GET /api/reports/active_sessions Retrieve active sessions. Query param: page.

PolicyLogic

Method Path Description
POST /api/policy/{file_id} Execute a PolicyLogic file against the supplied RADIUS-style request and return the result.

Example body:

{
  "User-Name": "user@domain.com",
  "Calling-Station-Id": "00:01:02:03:04:05",
  "User-Password": "test"
}

Utilities

Method Path Description
GET /api/utils/echo/{data} Echo back data. Useful for connectivity checks.
POST /api/utils/echo/ Echo back the request body.
GET /api/utils/timestamp Return the server's current timestamp.