Certificate tools
These tools manage Alpacon’s built-in PKI: certificate authorities (CAs) that sign certificates, certificate signing requests (CSRs) that request them, the certificates that get issued, and the revocation requests that invalidate them. They back requests like “create a CA for alpacax.com”, “request a certificate for web-01.internal”, or “revoke the certificate that’s about to expire.”
The typical lifecycle is: create a CA once per domain with create_certificate_authority, then request a certificate with create_sign_request—the CA is matched automatically from the requested domain or IP. An admin or CA owner approves the request with approve_sign_request, and the CA issues the certificate. If a certificate needs to be invalidated early, revoke_certificate starts a revocation request, which is auto-approved when the caller is the CA owner or an admin and otherwise waits for one to approve it.
All tools accept workspace (required) and region (optional, defaults to the configured region). These common parameters are omitted from the tables below.
Summary
| Tool | Description | Access |
|---|---|---|
list_certificate_authorities | List certificate authorities | Read-only |
create_certificate_authority | Create a certificate authority | Additive |
get_certificate_authority | Get certificate authority details | Read-only |
update_certificate_authority | Update a certificate authority’s validity periods or owner | Idempotent write |
delete_certificate_authority | Permanently delete a certificate authority | Destructive |
list_sign_requests | List certificate signing requests | Read-only |
create_sign_request | Create a certificate signing request | Additive |
get_sign_request | Get certificate signing request details | Read-only |
delete_sign_request | Cancel a pending certificate signing request | Destructive |
approve_sign_request | Approve a pending CSR so the CA issues the certificate | Additive |
deny_sign_request | Deny a certificate signing request | Destructive |
retry_sign_request | Retry a CSR stuck in the signing state | Idempotent write |
list_certificates | List issued certificates | Read-only |
get_certificate | Get certificate details | Read-only |
revoke_certificate | Create a revocation request for a certificate | Destructive |
list_revoke_requests | List certificate revocation requests | Read-only |
get_revoke_request | Get revocation request details | Read-only |
approve_revoke_request | Approve a pending revocation request | Destructive |
deny_revoke_request | Deny a pending revocation request | Destructive |
retry_revoke_request | Retry a revocation request stuck in the revoking state | Idempotent write |
cancel_revoke_request | Cancel a pending revocation request | Destructive |
Certificate authorities
A certificate authority (CA) is the root of trust that signs certificates for a domain. Each CA is hosted on a server (agent) and owned by a user. CLI equivalent: alpacon authority.
list_certificate_authorities
Lists certificate authorities configured in the workspace, including CA names, domains, validity periods, and key algorithm/size. Use this to discover available CAs before creating sign requests.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
page_size | integer | No | Number of items per page |
Example
“What certificate authorities do we have set up?”
The agent calls list_certificate_authorities and reports each CA’s name, domain, and validity settings.
create_certificate_authority
Creates a new CA for signing certificates within the workspace. Requires a name, root domain, organization, the server (agent) that hosts the CA, and an owner user. Optionally sets validity periods, key algorithm (rsa or ecdsa), key size (2048/4096 for RSA, 256/384 for ECDSA), and whether to install the CA automatically on the agent.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name of the certificate authority |
domain | string | Yes | Root domain of the CA; must be unique |
organization | string | Yes | Organization name that this CA belongs to |
server_id | string | Yes | Server (agent) UUID that runs this CA |
owner | string | Yes | Owner user UUID |
root_valid_days | integer | No | Validity of the root certificate in days |
default_valid_days | integer | No | Default validity for child certificates in days |
max_valid_days | integer | No | Maximum validity users can request in days |
key_algorithm | string | No | Key algorithm: rsa or ecdsa |
key_size | integer | No | Key size in bits: 2048/4096 for RSA, 256/384 for ECDSA |
install | boolean | No | Install the CA automatically on the agent |
Example
“Set up a certificate authority for alpacax.com, hosted on the ca-server agent”
The agent calls create_certificate_authority with domain="alpacax.com", the resolved server_id, and the requesting user as owner.
get_certificate_authority
Gets detailed information about a specific CA by ID: configuration, validity period, key algorithm/size, and status. Use list_certificate_authorities to discover CA IDs.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
ca_id | string | Yes | Certificate authority ID |
Example
“Show me the details of the alpacax.com CA”
The agent looks up the CA ID from list_certificate_authorities, then calls get_certificate_authority to return its full configuration.
update_certificate_authority
Updates an existing CA. This is a partial update—only the fields provided are changed. default_valid_days, max_valid_days, and owner are updatable; the CA’s name, domain, hosting server, and key parameters are immutable after creation. Requires admin or CA owner privileges.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
ca_id | string | Yes | Certificate authority ID |
default_valid_days | integer | No | New default validity for child certificates in days |
max_valid_days | integer | No | New maximum validity users can request in days |
owner | string | No | New owner user UUID |
Example
“Lower the max certificate validity on the alpacax.com CA to 90 days”
The agent calls update_certificate_authority with ca_id and max_valid_days=90; all other CA settings are left unchanged.
delete_certificate_authority
Permanently deletes a CA. This is irreversible—all certificates issued by this CA will no longer be verifiable. Requires admin or CA owner privileges.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
ca_id | string | Yes | Certificate authority ID to delete |
Example
“Delete the old staging CA, we don’t use it anymore”
The agent confirms the CA ID with the user before calling delete_certificate_authority, since the action cannot be undone.
Sign requests (CSRs)
A certificate signing request (CSR) asks a CA to issue a certificate. CSRs move through requested, signing, signed, failed, canceled, or denied states. CLI equivalent: alpacon csr.
list_sign_requests
Lists CSRs in the workspace, including status, common names, and associated CAs. Use this to review pending certificate requests.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
page_size | integer | No | Number of items per page |
Example
“Are there any certificate requests waiting for approval?”
The agent calls list_sign_requests and filters the results down to those in the requested state.
create_sign_request
Creates a CSR to request a new certificate. Provide at least one Subject Alternative Name via domain_list (DNS names) or ip_list (IP addresses)—at least one entry across the two is required. The CA is selected automatically by matching the SAN against each CA’s root domain, and the common name is derived from the first SAN entry; the organization is inherited from the matched CA.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
domain_list | array | No | Subject Alternative Names: DNS entries |
ip_list | array | No | Subject Alternative Names: IP addresses |
valid_days | integer | No | Certificate validity in days |
Example
“Request a certificate for web-01.alpacax.com”
The agent calls create_sign_request with domain_list=["web-01.alpacax.com"]; Alpacon matches it to the CA that owns the alpacax.com root domain.
get_sign_request
Gets detailed information about a specific CSR by ID: status, common name, SANs, associated CA, and processing details.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
csr_id | string | Yes | Certificate signing request ID |
Example
“What’s the status of the CSR for web-01.alpacax.com?”
The agent finds the CSR ID via list_sign_requests, then calls get_sign_request for its full status and processing details.
delete_sign_request
Cancels a CSR. Only requested (pending) CSRs can be canceled—the CSR transitions to the canceled state; CSRs already being processed or completed cannot be canceled this way. Requires admin, CA owner, or the original requester.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
csr_id | string | Yes | Certificate signing request ID to cancel |
Example
“Cancel the certificate request I just submitted for the wrong domain”
The agent calls delete_sign_request with the CSR ID; the request moves to canceled instead of being issued.
approve_sign_request
Approves a pending CSR so the CA issues the certificate. Use list_sign_requests to find pending CSRs. Requires admin or CA owner privileges.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
csr_id | string | Yes | Certificate signing request ID to approve |
Example
“Approve the pending CSR for web-01.alpacax.com”
The agent calls approve_sign_request with the CSR ID; the CA then issues the certificate.
deny_sign_request
Denies a CSR. Unlike approve_sign_request, there is no status guard, so a CSR in any state can be denied. The requester is notified of the decision. Requires admin or CA owner privileges.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
csr_id | string | Yes | Certificate signing request ID to deny |
Example
“Deny that CSR, the domain doesn’t belong to us”
The agent calls deny_sign_request with the CSR ID; the requester is notified.
retry_sign_request
Retries a CSR that’s stuck in the signing (processing) state by re-sending the request to the CA. Only CSRs in the signing state can be retried. Requires admin or CA owner privileges.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
csr_id | string | Yes | Certificate signing request ID to retry |
Example
“That CSR has been stuck signing for 10 minutes, try it again”
The agent calls retry_sign_request with the CSR ID to re-dispatch the request to the CA.
Certificates
Issued certificates are read-only from this API—certificates come into existence only through the sign request flow. CLI equivalent: alpacon cert.
list_certificates
Lists issued certificates in the workspace, including common names, expiry dates, and revocation status. Filterable by authority_id.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
authority_id | string | No | Filter by certificate authority ID |
page | integer | No | Page number for pagination |
page_size | integer | No | Number of items per page |
Example
“List all certificates issued by the alpacax.com CA”
The agent calls list_certificates with authority_id set to that CA’s ID.
get_certificate
Gets detailed information about a specific issued certificate by ID: content, common name, SANs, expiry date, and revocation status.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
certificate_id | string | Yes | Certificate ID |
Example
“When does the web-01.alpacax.com certificate expire?”
The agent finds the certificate ID via list_certificates, then calls get_certificate to check its expiry date.
revoke_certificate
Creates a revocation request to invalidate an issued certificate. Optionally include an RFC 5280 reason code and a free-text requested_reason. If the caller is the CA owner or an admin, the request is auto-approved and the certificate is revoked immediately; otherwise it waits for approval via approve_revoke_request.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
certificate_id | string | Yes | Certificate ID to revoke |
reason | integer | No | RFC 5280 revocation reason code (default: 0, unspecified). One of 0, 1, 2, 3, 4, 5, 6, 9, 10 |
requested_reason | string | No | Free-text explanation for the revocation |
Reason codes:
| Code | Reason |
|---|---|
| 0 | Unspecified |
| 1 | Key compromise |
| 2 | CA compromise |
| 3 | Affiliation changed |
| 4 | Superseded |
| 5 | Cessation of operation |
| 6 | Certificate hold |
| 9 | Privilege withdrawn |
| 10 | AA compromise |
Example
“Revoke the web-01.alpacax.com certificate, the key was compromised”
The agent calls revoke_certificate with certificate_id and reason=1. If the caller is the CA owner or an admin, the certificate is revoked immediately; otherwise the request waits for an admin or CA owner to approve it.
Revocation requests
A revocation request tracks the approval workflow for invalidating a certificate. revoke_certificate creates one; these tools review and manage it directly. Requests move through requested, revoking, revoked, failed, denied, or canceled states. CLI equivalent: alpacon revoke.
list_revoke_requests
Lists certificate revocation requests in the workspace along with their status. Use this to review pending revocation requests.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
page_size | integer | No | Number of items per page |
Example
“Are there any revocation requests waiting on my approval?”
The agent calls list_revoke_requests and filters the results down to those in the requested state.
get_revoke_request
Gets detailed information about a specific revocation request by ID: reason, status, and associated certificate.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
revoke_id | string | Yes | Revocation request ID |
Example
“What’s the status of the revocation request for that compromised certificate?”
The agent finds the revocation request ID via list_revoke_requests, then calls get_revoke_request for its status.
approve_revoke_request
Approves a pending revocation request. The certificate is revoked and added to the CRL (certificate revocation list) after approval. Requires admin or CA owner privileges.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
revoke_id | string | Yes | Revocation request ID to approve |
Example
“Approve that pending revocation request”
The agent calls approve_revoke_request with the revocation request ID; the certificate is revoked immediately.
deny_revoke_request
Denies a pending revocation request. The certificate remains valid. Requires admin or CA owner privileges.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
revoke_id | string | Yes | Revocation request ID to deny |
Example
“Deny that revocation request, the certificate is still needed”
The agent calls deny_revoke_request with the revocation request ID; the certificate stays valid.
retry_revoke_request
Retries a revocation request that’s stuck in the revoking state by re-sending the request to the CA. Only requests in the revoking state can be retried. Requires admin or CA owner privileges.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
revoke_id | string | Yes | Revocation request ID to retry |
Example
“That revocation has been stuck revoking for a while, try it again”
The agent calls retry_revoke_request with the revocation request ID to re-dispatch it to the CA.
cancel_revoke_request
Cancels a pending revocation request, withdrawing it before it’s approved. The request transitions to the canceled state and the certificate remains valid. Only requested (pending) revocation requests can be canceled. Requires admin, CA owner, or the original requester.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
revoke_id | string | Yes | Revocation request ID to cancel |
Example
“Actually don’t revoke that certificate, cancel the request”
The agent calls cancel_revoke_request with the revocation request ID; the certificate is unaffected.
Related
- Server management tools: find the server (agent) a CA is hosted on
alpacon authority: CLI equivalent for certificate authority managementalpacon csr: CLI equivalent for certificate signing requestsalpacon cert: CLI equivalent for issued certificatesalpacon revoke: CLI equivalent for revocation requests