SSL Teams API Reference
This page is the integration map for the public HTTP API. Use the versioned API documentation for the exact schema, and use the CLI command reference when you need an operator command rather than an HTTP call.
The SSL Teams service exposes a versioned JSON API under /api/v1. Protected endpoints require a valid bearer token and the permission for the requested operation. Team and environment scope is checked by the backend on every certificate operation.
The production service does not publish its OpenAPI description or Swagger UI. Use the generated OpenAPI build artifact or the versioned API documentation for request and response schemas. This page is a navigation map, not a replacement for the generated contract.
Public API endpoints
GET /api/v1/auth/public-key
The public key endpoint exposes JWT verification material, not the signing key.
Authentication
POST /api/v1/auth/token
POST /api/v1/auth/refresh
POST /api/v1/auth/logout
POST /api/v1/auth/logout-all
POST /api/v1/auth/password/change
GET /api/v1/auth/ping
The username/password token request is JSON with username, password, and
channel. The channel is a closed server vocabulary: use CLI for the
reusable client and WEB for browser sessions. The client sends CLI
automatically; it is not a client registration identifier.
The browser-assisted device flow uses the OAuth-style endpoints:
POST /oauth/device_authorization
POST /oauth/token
POST /oauth/device/prompt
POST /oauth/device/approve
POST /api/v1/auth/device/complete-initial-password
The device code is approved through the browser workflow. Do not place credentials or bearer tokens in URLs.
Device sign-in state
The server, not the browser, owns device sign-in state. A request moves through these states:
| State | Meaning |
|---|---|
PENDING |
Started by the CLI; no user has been verified yet. |
PASSWORD_CHANGE_REQUIRED |
A user proved a temporary password. The request is bound to that user until the password is changed. |
APPROVED |
Ready for the CLI to exchange exactly once. |
CONSUMED |
The CLI received its tokens. Terminal. |
SUPERSEDED, EXPIRED, DENIED |
Terminal. The CLI saves no session. |
POST /oauth/device/prompt returns userCode, clientId, scope, status, and expiresAt for a displayed code. It never claims a user.
POST /oauth/device/approve checks the username and password. A regular credential approves the request and returns 204. An initial or reset credential returns 409 with PASSWORD_CHANGE_REQUIRED and binds the request to that user. The browser then signs in with the temporary password and calls POST /api/v1/auth/device/complete-initial-password with userCode, currentPassword, and newPassword under the initial-session bearer token. That one call changes the password and approves the request in the same transaction, then returns a regular session. An initial-credential session may call only password change, device completion, and logout.
POST /api/v1/auth/password/change has no device side effect. Like device completion, it rejects an expired temporary password.
| HTTP | code |
Meaning |
|---|---|---|
401 |
AUTHENTICATION_FAILED |
Username or password rejected. Unknown, disabled, and wrong-password attempts return the same response. |
409 |
PASSWORD_CHANGE_REQUIRED |
The temporary password must be changed before the request can be approved. |
409 |
TEMPORARY_CREDENTIAL_EXPIRED |
The temporary password has expired; an administrator must reset it. |
409 |
DEVICE_FLOW_SUPERSEDED |
A newer sign-in replaced this request. |
409 |
DEVICE_FLOW_COMPLETED |
The request was already approved or consumed. |
409 |
DEVICE_FLOW_EXPIRED |
The request expired. Start a new one from the CLI. |
409 |
DEVICE_FLOW_INVALID |
Unknown code, or a request owned by another user. |
Polling POST /oauth/token returns OAuth error values: authorization_pending (also while a password change is pending), slow_down, expired_token, access_denied, device_flow_superseded, and invalid_grant.
Supersession
A newer successful sign-in by the same user, an ordinary password change, or an administrator credential reset supersedes that user's earlier claimed requests. Starting a request never supersedes another. Only the user who claimed a request can complete it, and the claim is bound to the credential version it was made with.
Application certificate authority
GET /api/v1/cert/application-ca/status
POST /api/v1/cert/application-ca/setup
POST /api/v1/cert/application-ca/complete
GET /api/v1/cert/application-ca/root
GET /api/v1/cert/application-ca/root/certificate
POST /api/v1/cert/application-ca/root/retire
POST /api/v1/cert/application-ca/root/revoke
GET /api/v1/cert/inventory?teamCode=<team>&environment=<environment>
The setup response is part of a one-time protected ceremony. Root private-key material must be handled transiently and must never be persisted or replayed by a browser client.
GET /api/v1/cert/application-ca/status returns the family readiness state and
Root lifecycle evidence. The familyStatus value is RETIRED after either
planned Root retirement or Root revocation, so clients must use the nullable
rootRetiredAt and rootRevokedAt fields to distinguish the actions:
{
"familyStatus": "RETIRED",
"applicationCaReady": false,
"leafIssuanceReady": false,
"rootRetiredAt": "<instant-or-null>",
"rootRevokedAt": "<instant-or-null>"
}
Root retirement records planned lifecycle evidence, stops issuance, and leaves descendant certificates unchanged. Root revocation records security evidence, revokes the issuing Intermediate and all non-deleted descendant leaves, and stops issuance. Both actions retain lifecycle history and require a new setup ceremony for a replacement family; the old family is never reactivated.
Intermediate retirement returns an Intermediate status of RETIRED and a
family status of DEGRADED without revoking leaves. Intermediate revocation
returns REVOKED for the Intermediate and its non-deleted descendant leaves,
keeps the family DEGRADED, and blocks issuance until a replacement
Intermediate is activated. Lifecycle and descendant audit records remain
available through the history and audit endpoints.
The inventory endpoint is the server-authoritative CA inventory for the selected
team and environment. It requires CERT_INTERMEDIATE_READ and returns only
public Root and Intermediate metadata:
{
"scope": { "team": "team-dev", "environment": "default" },
"items": [
{
"certificateId": "<uuid>",
"role": "ROOT",
"familyId": "<uuid>",
"rootId": "<uuid>",
"intermediateId": null,
"subjectDn": "CN=SSL Team Root CA",
"fingerprintSha256": "<64 hexadecimal characters>",
"status": "ACTIVE",
"notBefore": "<instant>",
"notAfter": "<instant>",
"version": 1
}
]
}
role is ROOT or INTERMEDIATE; status is ACTIVE, RETIRED,
REVOKED, or EXPIRED. Intermediate items include their rootId and
intermediateId. The response contains no private key or PEM material. Clients
must preserve both scope query parameters and must use the exact SHA-256
fingerprint, not an alias or subject, when matching local trust entries.
Intermediate certificates
GET /api/v1/cert/intermediates/current
GET /api/v1/cert/intermediates/history
GET /api/v1/cert/intermediates/requests
POST /api/v1/cert/intermediates/requests
POST /api/v1/cert/intermediates/requests/{requestId}/signed
POST /api/v1/cert/intermediates/by-name/{name}/signed
GET /api/v1/cert/intermediates/current/certificate
GET /api/v1/cert/intermediates/current/chain
POST /api/v1/cert/intermediates/{intermediateId}/retire
POST /api/v1/cert/intermediates/{intermediateId}/revoke
The browser API exposes only public Intermediate certificate material. The Intermediate private key remains server-side custody and is not a dashboard download because it is the signing authority used for leaf issuance; exporting it would allow an operator or compromised browser session to mint arbitrary descendant certificates outside the server's authorization, audit, lifecycle, and revocation controls. Intermediate replacement is performed through the CSR and externally signed certificate workflow instead of private-key delivery.
Leaf certificates
POST /api/v1/cert/leaves/generate
GET /api/v1/cert/leaves
GET /api/v1/cert/leaves/recently-expired
GET /api/v1/cert/leaves/{issuanceId}/attention
POST /api/v1/cert/leaves/{issuanceId}/revoke
GET /api/v1/cert/leaves/{issuanceId}/certificate
GET /api/v1/cert/leaves/{issuanceId}/chain
POST /api/v1/cert/leaves/{issuanceId}/artifact
Leaf generation and artifact re-download use the same JSON profile contract: outputProfile is BOTH, PKCS12_ONLY, or PEM_ONLY; PKCS#12 profiles require a strong pkcs12Password, and PEM_ONLY deliberately includes an unencrypted private key. The password is used only while creating the in-memory ZIP and is never written into the archive or manifest. Treat the ZIP as sensitive because it may contain private key material. Public certificate and chain downloads remain separate operations.
Audit and settings
GET /api/v1/cert/audit/revocations
GET /api/v1/cert/audit/{resourceType}/{resourceId}
GET /api/v1/security/settings/families
GET /api/v1/security/settings/families/{familyCode}
PUT /api/v1/security/settings/families/{familyCode}/values
Settings mutations use optimistic version checks. A stale version returns a conflict and must not mutate the record. Audit responses contain bounded security history; they are not a place to store or retrieve secrets.
Administration and runtime policy
These endpoints are permission-protected administrative operations rather than certificate issuance calls:
GET /api/v1/users
POST /api/v1/users
PUT /api/v1/users/{userId}
PUT /api/v1/users/{userId}/role
DELETE /api/v1/users/{userId}
POST /api/v1/users/{username}/credentials/reset
GET /api/v1/users/{username}/credentials/state
GET /api/v1/security/runtime-configuration
The user endpoints list active accounts, create accounts, update account details,
assign built-in roles, soft-delete accounts, issue one-time credentials, reset a
user's credential, or read credential state. Account update, role assignment,
and soft-delete requests include the current expected version where required.
The soft-delete request body is JSON with expectedVersion and a required
reason of at most 300 characters:
{
"expectedVersion": 3,
"reason": "Account no longer required"
}
Setting an account's status to DISABLED uses the account update endpoint,
keeps the account in normal listings, and revokes active sessions. Set the
status back to ACTIVE to re-enable it. DELETE /api/v1/users/{userId} is a
separate soft-delete operation: it removes the account from normal listings,
revokes active sessions, and retains its audit history.
The CLI exposes these routes as sslteam users list, show, create, update,
role, disable, enable, delete, reset-password, and credential-state; show is a local
lookup over the list response and does not add a separate REST route. The
runtime-configuration endpoint returns non-secret password-policy values for
authorized settings readers; it does not return password material.
Integration rules
- Use HTTPS and verify both the certificate chain and URL identity.
- Send bearer tokens only in the authorization header over the validated connection.
- Validate response schemas and handle
400,401,403,404, and409explicitly. - Send the current expected version for lifecycle mutations where the contract requires it.
- Preserve the correlation identifier from an error response when contacting an operator or support team.
- Never log authorization headers, tokens, private keys, passwords, CSRs, PEM bodies, or raw request and response bodies.
Java client
For Java applications, use the framework-neutral contracts with the typed client rather than duplicating JSON records or endpoint construction. The client accepts a caller-owned transport, so the embedding application remains responsible for TLS profiles and credential custody.
<dependency>
<groupId>com.jadaptive</groupId>
<artifactId>sslteam-api</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>com.jadaptive</groupId>
<artifactId>sslteam-client</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
import java.net.http.HttpClient;
import com.jadaptive.sslteam.client.PingResponse;
import com.jadaptive.sslteam.client.SslTeamClient;
import com.jadaptive.sslteam.client.SslTeamHttpTransport;
HttpClient httpClient = HttpClient.newHttpClient();
SslTeamHttpTransport transport = httpClient::send;
SslTeamClient client = new SslTeamClient(transport);
PingResponse ping = client.ping("https://sslteam.example.com", accessToken);
The client does not persist tokens, choose a filesystem layout, or grant server authorization. For origin-scoped TLS profiles, provide the caller-owned profile store to SslTeamTlsTransport.