Access API

Access API

Publish private applications, inspect access sessions, and request termination.

Access configuration uses enrolled gateways and published access policies. Network reachability and authorization have separate results.

Use the shared API contract for authentication, pagination, request headers, idempotency, and error responses.

Create an application

POST/organizations/{organization_id}/access-applications
Scope
access:write
Auth
Bearer API key

Creates a disabled private application until its identity, backend, and policy checks pass.

Request body
namestringrequired

Display name; does not change resource identity.

rule1–120 characters
asset_idstringrequired

Existing private service asset.

gateway_idstringrequired

Enrolled gateway authorized for the destination.

destinationstringrequired

Approved internal host or address.

portintegerrequired

Backend service port.

rule1–65535
protocolstringrequired

Supported application protocol.

one ofhttps, tcp
policy_idstringrequired

Published access-family policy.

201Created

Returns application ID, readiness checks, and ETag. No general subnet access is implied.

Read an application

GET/organizations/{organization_id}/access-applications/{application_id}
Scope
access:read
Auth
Bearer API key

Returns backend health, gateway status, policy adoption, and active session count.

200Result

Returns data and request_id.

Update application policy

PATCH/organizations/{organization_id}/access-applications/{application_id}
Scope
access:write
Auth
Bearer API key

Updates the application's assigned policy. Requires If-Match. New authorization decisions use the policy after gateway adoption; existing sessions follow their re-evaluation and expiry rules.

Request body
policy_idstringrequired

Replacement published access policy.

202Accepted

Returns application data and reconciliation operation. Check gateway adoption and session state separately.

List access sessions

GET/organizations/{organization_id}/access-sessions
Scope
access:read
Auth
Bearer API key

Returns session ID, user, device, application or VPN profile, gateway, posture decision, start time, and expiry. Standard limit and cursor apply. Unknown filters return 422.

Query parameters
application_idstringoptional

Filter private application.

gateway_idstringoptional

Filter executing gateway.

user_idstringoptional

Filter organization user.

activebooleanoptional

Whether to return active sessions. true selects observed active sessions; false selects inactive sessions. Omission includes both.

200Result

Returns a data array and pagination.next_cursor. Entries include stable IDs and the resource fields described for this collection.

Revoke a session

POST/organizations/{organization_id}/access-sessions/{session_id}/revoke
Scope
access:write
Auth
Bearer API key

Requests session termination. Requires authority over the application or VPN profile. Repetition preserves revocation intent; an offline gateway cannot immediately acknowledge termination.

Request body
reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
202Accepted

Returns session summary and termination operation. Success requires gateway acknowledgement.

Retire an application

POST/organizations/{organization_id}/access-applications/{application_id}/retire
Scope
access:write
Auth
Bearer API key

Retires an application by denying new admission and requesting active-session retirement. Requires If-Match; dependent routes must be reviewed.

Request body
reasonstringrequired

Audited justification. Empty values are invalid.

rule1–2000 characters
202Accepted

Returns a retirement operation. Verify session termination before removing the gateway destination.