Skip to main content
Version: 3.14.10.1

Combine TAP API

The Combine TAP API manages users, servers, groups, AWS role assignments, certificates, alert events, configuration, metadata, and operational tools for a Combine deployment. The CAP- and SCAP-compatible endpoints that issue temporary AWS credentials are documented separately in the CAP / SCAP API section.

All requests must use HTTPS, except the health check and the OCSP responder, which are also served over HTTP. Except where explicitly noted, requests require mutual TLS with a valid client certificate issued for the deployment. There is no login step: the certificate's serial number identifies the caller's user account, and that account's role (user, admin, or super_admin) determines what the caller can access. Each authenticated request sets the account's lastConsoleLoginDate to the current UTC date (YYYY-MM-DD). A request over plain HTTP, without a valid client certificate, with a revoked certificate, or for an unknown or inactive account receives the Combine HTML error page, with HTTP status 200, instead of a JSON response. So does a request whose authentication fails unexpectedly.

The Users and Servers endpoints are available in two versions. Version v1 (/tap/api/v1/users and /tap/api/v1/servers) returns every user or server in full from the list endpoints and returns a presigned download link in bundlePath. Version v2 (/tap/api/v2/users and /tap/api/v2/servers) returns a summary of each user or server from the list endpoints, with optional paging and search, and returns the stored location of the certificate bundle in bundlePath. Every other endpoint uses /tap/api/v1.

Responses of at least 1,024 bytes, or of unknown length, with a content type of application/json, text/plain, text/html, text/css, or application/javascript are compressed with gzip when the request's Accept-Encoding header accepts gzip. Compression is set in the TAP server's HTTP and HTTPS connectors and is not controlled by a Configuration Value.

Requests that modify data must include the X-Requested-By header, with any value; this applies to every method except GET and HEAD, on every path except the health check and the OCSP responder. The header is checked before authentication. A request that omits it is rejected with 400 and an empty body. Administrative operations require an account with the admin role; the super_admin role satisfies every role check. A caller without the required role receives 403, except on POST /tap/api/v1/admin/certificate/custom, which returns 500.

A request to a path that no endpoint serves, and a 404 that an operation returns without a body, receive the Combine HTML not-found page with 404; a PUT, PATCH, or DELETE request to a path that no endpoint serves receives 405 with the Combine HTML error page instead. Any other error status that an operation returns without a body, including 405 for an unsupported method, 406 for an Accept header that excludes every content type the operation returns, 415 for an unsupported Content-Type, and 500 for an unhandled server error, receives the Combine HTML error page with that status.

When the combine.tap.application.cors.enable Configuration Value is true (default false), every response carries the Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers, Access-Control-Allow-Credentials, and Referrer-Policy headers set by the combine.tap.application.cors.* Configuration Values, and every OPTIONS request is answered with 200 and an empty body before the X-Requested-By and authentication checks.

For a step-by-step guide with curl and Python examples, see Call the TAP API.

Authentication​

Authenticates the caller with an X.509 client certificate issued by the deployment. Combine identifies the caller's user account from the certificate's serial number, and that account's role determines what the caller can access.