List Client CAs

GET /v1/client-cas

List the account's client CAs: the X.509 root CAs uploaded for mTLS validation, and the CAs managed by ngris ("kind": "managed"), which issue your devices' certificates. Once uploaded, a client CA can be attached to one or more endpoints via PUT /v1/endpoints/{uuid}/mtls — clients connecting to that endpoint must present a leaf cert chained to one of the trusted roots, or the TLS handshake fails at the edge.

Account scope: these client CAs belong to your active account and are shared with its members per your role's permissions. Use switch account to manage a different account's CAs.

Use this for service-to-service auth where every caller has a unique client cert (issued by your own internal PKI), or for high-assurance deployments where password/token auth alone isn't enough.

Listed CAs include an endpoint_count showing how many endpoints currently use each CA — non-zero counts block deletion until you detach.

Query parameters

page int
Optional. 1-based page number. Omit it to get every CA in one response.
page_size int
Optional. CAs per page when page is sent. Default 15, capped at 200.
q string
Optional. Case-insensitive match on the name, subject CN, issuer CN or fingerprint.
expiry string
Optional. expired, expiring (within 30 days) or valid.
usage string
Optional. attached (trusted by at least one endpoint) or unused.

Response (200 OK)

items array
Client CAs ordered by created_at DESC. [] when there are none.
page, page_size int
The page returned and the effective page size. Both 0 when page was not sent (the whole list).
total int
Number of matching CAs across all pages.
items[].uuid string (uuid)
The CA's uuid. Used in /client-cas/{uuid} and in the mTLS config as ca_uuids[].
items[].user_uuid string (uuid)?
The user who uploaded the CA. Omitted once that user is deleted.
items[].name string
Friendly label. Max 128 chars.
items[].description string
Optional longer description. Max 512 chars.
items[].subject_cn string
Subject Common Name from the CA cert.
items[].subject_raw string
Full RFC 4514 subject DN.
items[].issuer_cn, issuer_raw string
Issuer (typically the CA itself for self-signed roots).
items[].fingerprint string
SHA-256 fingerprint (hex). Unique per account — uploading a CA the account already has answers that CA (200, "existing": true).
items[].not_before, not_after datetime
CA validity window. Expired CAs still appear in the list but won't validate any leaf cert that chains to them.
items[].kind string
uploaded: a CA you uploaded. managed: a CA ngris created for the account, which issues device certificates.
items[].active_certificates int?
Managed CAs only: how many of the certificates it issued are active (not revoked, not expired). List them.
items[].endpoint_count int
How many endpoints currently trust this CA. Non-zero blocks deletion.
items[].quota_paused_at datetime?
Set while the CA is paused because the account has more client CAs (or managed CAs) than its plan allows: kept, but endpoints don't trust it until the account has room again (it resumes on its own). Absent otherwise.
items[].created_at, updated_at datetime
RFC 3339 UTC timestamps.

Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.

Errors

401 Unauthorized
Missing auth.
403 Forbidden
Caller lacks the cert:read permission in the active account.
Request
curl "https://api.ngris.com/v1/client-cas" \ -H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris client = Ngris(api_key="<your_api_key>") result = client.client_cas.list() for ca in result["items"]: print(f"{ca['uuid']} {ca['name']} ({ca['endpoint_count']} endpoints)")
Response — 200 OK
{ "items": [ { "uuid": "019af8a2-4b16-70ea-8090-9f63343250c8", "user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134", "name": "internal-corp-ca", "description": "Acme Corp internal PKI root", "subject_cn": "Acme Corp Root CA", "subject_raw": "CN=Acme Corp Root CA,O=Acme Corp,C=US", "issuer_cn": "Acme Corp Root CA", "issuer_raw": "CN=Acme Corp Root CA,O=Acme Corp,C=US", "fingerprint": "ab:cd:ef:01:23:...", "not_before": "2024-01-01T00:00:00Z", "not_after": "2034-01-01T00:00:00Z", "endpoint_count": 2, "kind": "uploaded", "created_at": "2026-01-15T12:00:00Z", "updated_at": "2026-01-15T12:00:00Z" }, { "uuid": "019b2c40-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134", "name": "Company laptops", "description": "", "subject_cn": "Company laptops", "subject_raw": "CN=Company laptops,O=ngris managed client CA", "issuer_cn": "Company laptops", "issuer_raw": "CN=Company laptops,O=ngris managed client CA", "fingerprint": "3f:a9:1c:...", "not_before": "2026-10-29T10:00:00Z", "not_after": "2036-10-29T10:00:00Z", "endpoint_count": 1, "kind": "managed", "active_certificates": 12, "created_at": "2026-10-29T10:00:00Z", "updated_at": "2026-10-29T10:00:00Z" } ], "page": 0, "page_size": 0, "total": 2 }
Was this helpful?
On this page
List Client CAs
Was this helpful?
Homepage Docs Dashboard Docs API Docs nvelox Dashboard