Skip to main content
Version: 3.15.1.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 that fails authentication receives an ErrorResponse ({"success": false, "message": "..."}) instead of reaching the endpoint: 400 over plain HTTP ("This Request is not supported over an HTTP connection. Please retry over an HTTPS connection."), 401 without a client certificate ("This Request does not have a valid Client Certificate.") or with a revoked certificate ("This Request has a Client Certificate that is revoked."), and 403 for an unknown account ("This User Account is not recognized.", also returned when the account cannot be read) or an inactive account ("This User Account is not active."). A request that looks like a browser navigation, because it sends Sec-Fetch-Mode: navigate or an Accept header that contains text/html, receives the same status with the Combine HTML error page instead. An unexpected failure during authentication returns the Combine HTML error page with status 200.

This reference documents every endpoint at version v3 (/tap/api/v3). Versions v1 and v2 are DEPRECATED and will be removed in a future version of Combine. Every endpoint documented at /tap/api/v3 also answers, identically, at the /tap/api/v1 and /tap/api/v2 prefixes, except the Users and Servers entity operations, which differ by version and are documented separately as deprecated operations: in v1, the list endpoints return every user or server in full and bundlePath is a presigned download link; in v1 and v2, awsRoles is returned as a list of AWS Role objects and accepted as a list of AWS Role objects or AWS Role ids; in v3, awsRoles is returned and accepted only as a list of AWS Role ids. The OCSP responder and the AWS console login keep their fixed /tap/api/v1 paths, and the health check is at /combine/api/health. A request to any other version segment, such as /tap/api/v4, matches no endpoint and is answered like any other unknown path, as described below.

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 ErrorResponse with the message "This request could not be verified." (the Combine HTML error page for a browser navigation). Administrative operations require an account with the admin role, and some require the super_admin role; the super_admin role satisfies every role check. A caller without the required role receives 403 with an ErrorResponse.

A request to a path that no endpoint serves, and a 404 that an operation returns without a body, receive 404 with {"success": false, "message": "Not Found"}; a PUT, PATCH, or DELETE request to a path that no endpoint serves receives 405 with {"success": false, "message": "An unexpected error occurred."} 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 {"success": false, "message": "An unexpected error occurred."} with that status. A browser navigation receives the Combine HTML error page instead of either body.

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.