> For the complete documentation index, see [llms.txt](https://docs.toolkit.equs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolkit.equs.ai/api/control-api/access-certificates.md).

# Access Certificates

\[Experimental]

## \[Experimental] Create an Access CA enrolment

> Creates an EC P-256 signing key in the key management service and returns a PKCS#10 certificate signing request over its public half, for submission to an external Access CA. Each call creates its own enrolment.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Access Certificates","description":"[Experimental]"}],"security":[{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"CreateAccessCertEnrolmentResponse":{"type":"object","properties":{"id":{"type":"string","description":"Access certificate unique ID"},"csrPem":{"type":"string","description":"PKCS#10 certificate signing request, PEM. Submit this to the Access CA; the private key it certifies never leaves the key management service."},"createdAt":{"format":"date-time","type":"string","description":"Date and time the enrolment was created."}},"required":["id","csrPem","createdAt"]}}},"paths":{"/api/v1/access-certificates/enrolment":{"post":{"description":"Creates an EC P-256 signing key in the key management service and returns a PKCS#10 certificate signing request over its public half, for submission to an external Access CA. Each call creates its own enrolment.","operationId":"AccessCertController_createEnrolment_api/v1","parameters":[],"responses":{"201":{"description":"When a signing key is created and a certificate signing request is emitted over it. Earlier enrolments are left outstanding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccessCertEnrolmentResponse"}}}}},"summary":"[Experimental] Create an Access CA enrolment","tags":["Access Certificates"]}}}}
```

## \[Experimental] Get an Access CA enrolment

> Returns that enrolment's certificate signing request. A pure read — it creates no new signing key.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Access Certificates","description":"[Experimental]"}],"security":[{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"GetAccessCertEnrolmentResponse":{"type":"object","properties":{"id":{"type":"string","description":"Access certificate unique ID"},"csrPem":{"type":"string","description":"PKCS#10 certificate signing request, PEM. Submit this to the Access CA; the private key it certifies never leaves the key management service."},"createdAt":{"format":"date-time","type":"string","description":"Date and time the enrolment was created."}},"required":["id","csrPem","createdAt"]}}},"paths":{"/api/v1/access-certificates/enrolment/{id}":{"get":{"description":"Returns that enrolment's certificate signing request. A pure read — it creates no new signing key.","operationId":"AccessCertController_getEnrolment_api/v1","parameters":[{"name":"id","required":true,"in":"path","description":"Access certificate enrolment unique ID","schema":{"type":"string"}}],"responses":{"200":{"description":"When the pending certificate signing request is returned unchanged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAccessCertEnrolmentResponse"}}}},"404":{"description":"When no pending enrolment with that ID exists"}},"summary":"[Experimental] Get an Access CA enrolment","tags":["Access Certificates"]}}}}
```

## \[Experimental] Get the RP request-signing trust anchor

> Returns the anchor of the active access certificate.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Access Certificates","description":"[Experimental]"}],"security":[{"sp":[]},{"tenant":[]},{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"GetAccessCertTrustAnchorResponse":{"type":"object","properties":{"certPem":{"type":"object","nullable":true,"description":"Trust anchor certificate, PEM. Load this into the wallet trust list; it is never sent in the request `x5c`. Null when an imported chain arrived without its root — obtain it from `issuerDn` out of band."},"subjectKeyId":{"type":"object","nullable":true,"description":"Subject Key Identifier of the anchor, hex. Matches the AKID of the certificate it issued. Null when no anchor certificate is held."},"notBefore":{"type":"object","nullable":true,"description":"Start of the anchor validity window. Null when no anchor certificate is held."},"notAfter":{"type":"object","nullable":true,"description":"End of the anchor validity window. Past it, wallets holding this anchor reject every request signed under it. Null when no anchor certificate is held."},"issuerDn":{"type":"string","description":"Issuer Distinguished Name of the topmost certificate in the emitted chain. Identifies who to obtain the anchor from when it is not held here."}},"required":["issuerDn"]}}},"paths":{"/api/v1/access-certificates/trust-anchor":{"get":{"description":"Returns the anchor of the active access certificate.","operationId":"AccessCertController_getTrustAnchor_api/v1","parameters":[],"responses":{"200":{"description":"When the request-signing trust anchor is retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAccessCertTrustAnchorResponse"}}}},"404":{"description":"When no access certificate is active, so no anchor exists.This is the expected response until an operator enrols with an external Access CA, imports the issued chain and activates it"}},"summary":"[Experimental] Get the RP request-signing trust anchor","tags":["Access Certificates"]}}}}
```

## \[Experimental] Import an Access CA certificate chain

> Binds a chain issued by an external Access CA to the key of the enrolment named in the body. Stored inactive: import never changes what Verifiers present.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Access Certificates","description":"[Experimental]"}],"security":[{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"ImportAccessCertRequest":{"type":"object","properties":{"enrolmentId":{"type":"string","description":"Access certificate enrolment unique ID"},"chainPem":{"type":"string","description":"Certificate chain from the Access CA, PEM, leaf first. The leaf must certify the key of the named enrolment. A trailing self-signed root is retained as the trust anchor rather than emitted in `x5c`."}},"required":["enrolmentId","chainPem"]},"ImportAccessCertResponse":{"type":"object","properties":{"id":{"type":"string","description":"Access certificate unique ID"},"notBefore":{"type":"object","nullable":true,"description":"Start of the leaf validity window. Null while the certificate is a pending enrolment with no chain bound."},"notAfter":{"type":"object","nullable":true,"description":"End of the leaf validity window. Past it, x509 Verifiers fail authorization request creation closed."},"activatedAt":{"type":"object","nullable":true,"description":"When the certificate was last activated. Null if it has never been the one Verifiers present."},"supersededAt":{"type":"object","nullable":true,"description":"When the certificate stopped being the active one. Set on deactivation and when another certificate is activated in its place; superseded rows are retained so sessions created under them still verify."},"revokedAt":{"type":"object","nullable":true,"description":"When the certificate was revoked. Terminal — a revoked certificate can never be activated again."},"createdAt":{"format":"date-time","type":"string","description":"Date and time the certificate record was created."}},"required":["id","createdAt"]}}},"paths":{"/api/v1/access-certificates/import/chain":{"post":{"description":"Binds a chain issued by an external Access CA to the key of the enrolment named in the body. Stored inactive: import never changes what Verifiers present.","operationId":"AccessCertController_importChain_api/v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportAccessCertRequest"}}}},"responses":{"201":{"description":"When the chain is bound to the pending enrolment. Stored inactive — activation is a separate call","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportAccessCertResponse"}}}},"404":{"description":"When no pending enrolment with that ID exists, so there is no key to bind the chain to"},"422":{"description":"When the chain is unparseable, is not ordered leaf-first, has a self-signed leaf, is outside its validity window, or its leaf does not certify the pending enrolment key"}},"summary":"[Experimental] Import an Access CA certificate chain","tags":["Access Certificates"]}}}}
```

## \[Experimental] Import a key and chain from a PKCS#12 container

> For Access CAs that generate the signing key themselves. The private key is installed into the key management service and is never retained by the application; the chain is stored inactive. Where the key management service will not accept external key material, the import is refused and the error names the certificate signing request flow instead.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Access Certificates","description":"[Experimental]"}],"security":[{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"ImportPkcs12AccessCertRequest":{"type":"object","properties":{"container":{"type":"string","description":"The PKCS#12 container as delivered by the Access CA, base64 of its DER bytes. It must hold one EC P-256 private key and the certificates for it. Only PBES2 (AES-CBC) protection is supported."},"passphrase":{"type":"string","description":"Passphrase protecting the container. Used once to decrypt it and never stored or logged."}},"required":["container","passphrase"]},"ImportPkcs12AccessCertResponse":{"type":"object","properties":{"id":{"type":"string","description":"Access certificate unique ID"},"notBefore":{"type":"object","nullable":true,"description":"Start of the leaf validity window. Null while the certificate is a pending enrolment with no chain bound."},"notAfter":{"type":"object","nullable":true,"description":"End of the leaf validity window. Past it, x509 Verifiers fail authorization request creation closed."},"activatedAt":{"type":"object","nullable":true,"description":"When the certificate was last activated. Null if it has never been the one Verifiers present."},"supersededAt":{"type":"object","nullable":true,"description":"When the certificate stopped being the active one. Set on deactivation and when another certificate is activated in its place; superseded rows are retained so sessions created under them still verify."},"revokedAt":{"type":"object","nullable":true,"description":"When the certificate was revoked. Terminal — a revoked certificate can never be activated again."},"createdAt":{"format":"date-time","type":"string","description":"Date and time the certificate record was created."}},"required":["id","createdAt"]}}},"paths":{"/api/v1/access-certificates/import/pkcs12":{"post":{"description":"For Access CAs that generate the signing key themselves. The private key is installed into the key management service and is never retained by the application; the chain is stored inactive. Where the key management service will not accept external key material, the import is refused and the error names the certificate signing request flow instead.","operationId":"AccessCertController_importPkcs12_api/v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportPkcs12AccessCertRequest"}}}},"responses":{"201":{"description":"When the private key is installed into the key management service and its chain stored, inactive. The plaintext key is not retained by the application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportPkcs12AccessCertResponse"}}}},"422":{"description":"When the container cannot be read or decrypted with the passphrase, is protected with an algorithm other than PBES2holds a key that is not EC P-256, holds certificates that form no chain for that key, has a self-signed leaf,is outside its validity window, or when the key management service will not accept externally generated key material —in which case the error names the certificate signing request flow as the alternative"}},"summary":"[Experimental] Import a key and chain from a PKCS#12 container","tags":["Access Certificates"]}}}}
```

## \[Experimental] Activate a access certificate

> Makes the certificate the one every x509 Verifier presents.This changes the RP Client Identifier under the x509\_hash prefix, so the response reports the resulting identifiers.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Access Certificates","description":"[Experimental]"}],"security":[{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"ActivateAccessCertResponse":{"type":"object","properties":{"certificate":{"description":"The now-active certificate.","allOf":[{"$ref":"#/components/schemas/AccessCertOutput"}]},"clientIdHash":{"type":"string","description":"Client Identifier that Verifiers using the x509_hash prefix now emit, derived from this certificate leaf."},"clientIdSanDns":{"type":"object","nullable":true,"description":"Client Identifier that Verifiers using the x509_san_dns prefix now emit, taken from the leaf `dNSName` SAN, or null when the leaf carries no `dNSName` SAN (e.g. an x509_hash-only pilot certificate)."},"previousClientIdHash":{"type":"object","nullable":true,"description":"The x509_hash Client Identifier emitted before this activation, or null if nothing was active. Anything keyed to it in a wallet or ecosystem trust list must be updated."}},"required":["certificate","clientIdHash"]},"AccessCertOutput":{"type":"object","properties":{"id":{"type":"string","description":"Access certificate unique ID"},"notBefore":{"type":"object","nullable":true,"description":"Start of the leaf validity window. Null while the certificate is a pending enrolment with no chain bound."},"notAfter":{"type":"object","nullable":true,"description":"End of the leaf validity window. Past it, x509 Verifiers fail authorization request creation closed."},"activatedAt":{"type":"object","nullable":true,"description":"When the certificate was last activated. Null if it has never been the one Verifiers present."},"supersededAt":{"type":"object","nullable":true,"description":"When the certificate stopped being the active one. Set on deactivation and when another certificate is activated in its place; superseded rows are retained so sessions created under them still verify."},"revokedAt":{"type":"object","nullable":true,"description":"When the certificate was revoked. Terminal — a revoked certificate can never be activated again."},"createdAt":{"format":"date-time","type":"string","description":"Date and time the certificate record was created."}},"required":["id","createdAt"]}}},"paths":{"/api/v1/access-certificates/{id}/activate":{"post":{"description":"Makes the certificate the one every x509 Verifier presents.This changes the RP Client Identifier under the x509_hash prefix, so the response reports the resulting identifiers.","operationId":"AccessCertController_activate_api/v1","parameters":[{"name":"id","required":true,"in":"path","description":"Access certificate unique ID","schema":{"type":"string"}}],"responses":{"200":{"description":"When the certificate becomes the one every x509 Verifier presents. The response states the resulting Client Identifiers, and the previous one when it changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateAccessCertResponse"}}}},"404":{"description":"When no certificate with that ID exists"},"422":{"description":"When the certificate is expired or not yet valid, has been revoked,or a Verifier uses the x509_san_dns prefix and the leaf carries no matching dNSName SAN"}},"summary":"[Experimental] Activate a access certificate","tags":["Access Certificates"]}}}}
```

## \[Experimental] Deactivate the active access certificate

> Leaves the deployment with no active certificate, failing x509 Verifiers closed.To revert a bad activation, activate the superseded certificate instead.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Access Certificates","description":"[Experimental]"}],"security":[{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"DeactivateAccessCertResponse":{"type":"object","properties":{"id":{"type":"string","description":"Access certificate unique ID"},"notBefore":{"type":"object","nullable":true,"description":"Start of the leaf validity window. Null while the certificate is a pending enrolment with no chain bound."},"notAfter":{"type":"object","nullable":true,"description":"End of the leaf validity window. Past it, x509 Verifiers fail authorization request creation closed."},"activatedAt":{"type":"object","nullable":true,"description":"When the certificate was last activated. Null if it has never been the one Verifiers present."},"supersededAt":{"type":"object","nullable":true,"description":"When the certificate stopped being the active one. Set on deactivation and when another certificate is activated in its place; superseded rows are retained so sessions created under them still verify."},"revokedAt":{"type":"object","nullable":true,"description":"When the certificate was revoked. Terminal — a revoked certificate can never be activated again."},"createdAt":{"format":"date-time","type":"string","description":"Date and time the certificate record was created."}},"required":["id","createdAt"]}}},"paths":{"/api/v1/access-certificates/deactivate":{"post":{"description":"Leaves the deployment with no active certificate, failing x509 Verifiers closed.To revert a bad activation, activate the superseded certificate instead.","operationId":"AccessCertController_deactivate_api/v1","parameters":[],"responses":{"200":{"description":"When the deployment is left with no active certificate. x509 Verifiers then fail authorization request creation closed until one is activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeactivateAccessCertResponse"}}}},"409":{"description":"When no certificate is active"}},"summary":"[Experimental] Deactivate the active access certificate","tags":["Access Certificates"]}}}}
```

## \[Experimental] Revoke a access certificate

> Records that the certificate must never be used again, for the case where the Access CA has revoked it.Deactivates it if active.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Access Certificates","description":"[Experimental]"}],"security":[{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"RevokeAccessCertResponse":{"type":"object","properties":{"id":{"type":"string","description":"Access certificate unique ID"},"notBefore":{"type":"object","nullable":true,"description":"Start of the leaf validity window. Null while the certificate is a pending enrolment with no chain bound."},"notAfter":{"type":"object","nullable":true,"description":"End of the leaf validity window. Past it, x509 Verifiers fail authorization request creation closed."},"activatedAt":{"type":"object","nullable":true,"description":"When the certificate was last activated. Null if it has never been the one Verifiers present."},"supersededAt":{"type":"object","nullable":true,"description":"When the certificate stopped being the active one. Set on deactivation and when another certificate is activated in its place; superseded rows are retained so sessions created under them still verify."},"revokedAt":{"type":"object","nullable":true,"description":"When the certificate was revoked. Terminal — a revoked certificate can never be activated again."},"createdAt":{"format":"date-time","type":"string","description":"Date and time the certificate record was created."}},"required":["id","createdAt"]}}},"paths":{"/api/v1/access-certificates/{id}/revoke":{"post":{"description":"Records that the certificate must never be used again, for the case where the Access CA has revoked it.Deactivates it if active.","operationId":"AccessCertController_revoke_api/v1","parameters":[{"name":"id","required":true,"in":"path","description":"Access certificate unique ID","schema":{"type":"string"}}],"responses":{"200":{"description":"When the certificate is marked revoked. Terminal — it is deactivated if it was active and can never be activated again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeAccessCertResponse"}}}},"404":{"description":"When no certificate with that ID exists"}},"summary":"[Experimental] Revoke a access certificate","tags":["Access Certificates"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.toolkit.equs.ai/api/control-api/access-certificates.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.