Public API

The dashboard is built on a REST API, and your own tools can use the same API. What the dashboard does to devices, groups, access rules, networks, DNS, enrollment keys and members, a script can do over HTTPS. It can keep access rules in version control, fill groups from an inventory, copy Activity into a log system, or check in a test what a device can reach.

The base URL is https://app.sxaccess.com, and every path starts with /api. Requests and responses are JSON.

Every request carries an access token in the Authorization header, after the word Token: Authorization: Token sxp_.... Tokens always start with sxp_, so secret scanners can recognise one that leaks into a repository or a log.

Issue tokens to a service account rather than to a person. The automation then keeps working when people leave, and Activity names the service account as the one who made each change. Members whose role is owner, admin or network admin can also create a token for themselves, under Profile Settings → Tokens in the account menu; that token stops working when the member is blocked or removed. A token acts with the role of its account, in the organization it was issued in - see Roles.

The dashboard calls the same API with the sign-in session of the person using it; scripts and tools use an access token. Paths under /api/auth/ serve the sign-in pages and take no token.

Every call acts in one organization. An access token always acts in the organization it was issued in, so a tool that manages two organizations needs a token from each. GET /api/organizations returns the organization a call acts in, as a list with one entry.

A person who is a member of several organizations and calls the API with their sign-in session picks one with the X-Organization-Id header, set to the organization's ID; without it, the call acts in their default organization. Access tokens do not need the header, and it does not move a token to another organization. Organizations covers creating and switching organizations.

A token can do what the role of its account allows in that organization, and nothing more. The role is read again on every request, so a change of role applies from the next call. Service accounts may read everything in their organization whatever their role; the role decides what they may change. The full matrix is in Roles and permissions.

Paths are written as the API names them. A collection answers GET with a list and POST with a new object, and an object's own path, such as /api/groups/{groupId}, answers GET, PUT and DELETE. The table notes the exceptions.

• Identifiers are opaque strings such as p64dm3gk7ku6rc5asbde. Read them from the API; do not parse them or make them up.
• References are by ID. An access rule names group IDs, not group names, so look the groups up first. An ID that names no group in the organization is left out of the rule rather than refused, so check that every lookup found one.
• Bodies are strict. A request body may hold only the fields its schema lists, at every depth. Any other field is refused with 400 and a message that names it.
• PUT replaces. Build the body from what GET returned: keep every field the request accepts, change the ones you mean to change, and leave out fields the request does not list, such as id.

Every error has the same body: {"message": "...", "code": 403, "error_code": "..."}. code repeats the HTTP status, and message is written for people. error_code is present only where a client has to tell failures apart; branch on it, never on the text of message.

The examples run in a POSIX shell with curl and jq. Set the token and two shorthands once, then check that the token works; the token comes from your secret store. The check prints 200 when the token works, and 401 when it is missing, expired or wrong.

The list holds every device in the organization, with its overlay address and whether it is connected right now.

Working out from the access rules what a device can reach is error-prone. /api/devices/{deviceId}/reachable-devices gives the answer after every access rule and device requirement has been evaluated: the devices this device may connect to and the devices allowed to connect to it, including the routing devices that carry its traffic to network resources. Protocols and ports are not part of the answer; the access rules decide those.

Set DEVICE to the device's id from GET /api/devices. The second example exits with a non-zero status unless db-01 is in the answer, which makes this endpoint the right thing to check in a test.

This lets Engineering reach Production databases on TCP 5432, one way. It needs a token whose role may change access rules: owner, admin or network admin. The rule refers to groups by ID, so the first block looks both groups up and prints their IDs. Check that neither is empty: an ID that names no group is left out of the rule rather than refused.

"bidirectional": false makes the rule one-way; true also lets the destinations open connections to the sources. Add source_device_requirements with the IDs of device requirements to require them of the sources. Afterwards, ask what a device in Engineering can reach to confirm the rule does what you meant.

PUT /api/organizations/{organizationId} takes the organization's settings as one object. Read them with GET, change what you mean to change, and send the complete settings object back. This example sets the Session length of devices enrolled by signing in (Settings → Security; it applies while Expire device sessions is on) to 12 hours. It needs an owner's or an admin's token. The first block reads the organization the token acts in. The second sends the complete settings object back with one change: device_login_expiration is the session length in seconds, so 43200 is 12 hours.

If you manage SXAccess with Terraform, its provider calls this same API, so treat it like any other client: a service account and a token of its own, with the narrowest role that covers what it manages. Keeping groups, access rules, networks, routes and DNS in code gives you review before a change, history after it, and a quick answer to what changed when something breaks.