> 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/verifier.md).

# Verifier

## Get Verifiers

> Get paginated Verifiers

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"GetVerifiersResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ResponseItem"}},"pagination":{"$ref":"#/components/schemas/PaginationData"}},"required":["items","pagination"]},"ResponseItem":{"type":"object","properties":{"id":{"type":"string","description":"Verifier unique ID"},"name":{"type":"string","description":"Display name of the verifier."},"logo":{"description":"Logo displayed for this verifier when requesting presentations.","allOf":[{"$ref":"#/components/schemas/Logo"}]},"didMethod":{"type":"string","description":"DID method used to generate the DID for this verifier.","enum":["did:web"]},"clientIdPrefix":{"type":"string","enum":["did_web","x509_hash","x509_san_dns"],"description":"OID4VP Client Identifier Prefix this verifier presents itself with.The x509 values are backed by a request-signing certificate;`did_web` resolves the identifier through the verifier DID document."},"status":{"type":"string","description":"Current status of the verifier.","enum":["active","deactivated"]},"requiresIntendedUse":{"type":"boolean","description":"Whether this verifier attests a registered purpose. Set by registering the first intended use. While true, every presentation request must name an intended use."},"createdAt":{"format":"date-time","type":"string","description":"Date and time the verifier was created."},"trustedRootCerts":{"description":"Base64-encoded X.509 root certificates trusted when verifying presented credentials.","type":"array","items":{"type":"string"}}},"required":["id","name","didMethod","clientIdPrefix","status","requiresIntendedUse","createdAt"]},"Logo":{"type":"object","properties":{"uri":{"type":"string","format":"uri","description":"Publicly accessible URL of the logo image."},"altText":{"type":"string","description":"Alternative text describing the logo, used for accessibility."}},"required":["uri"]},"PaginationData":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"}},"required":["page","limit"]}}},"paths":{"/api/v1/verifiers":{"get":{"description":"Get paginated Verifiers","operationId":"VerifierController_getVerifiers_api/v1","parameters":[{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"default":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"default":"date","type":"string","enum":["name","status","date"]}},{"name":"order","required":false,"in":"query","description":"Sort direction","schema":{"default":"asc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"When Verifiers are retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVerifiersResponse"}}}}},"summary":"Get Verifiers","tags":["Verifier"]}}}}
```

## Create Verifier

> Create new Verifier

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"CreateVerifierRequest":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the verifier."},"logo":{"description":"Logo displayed for this verifier when requesting presentations.","allOf":[{"$ref":"#/components/schemas/Logo"}]},"didMethod":{"type":"string","description":"DID method used to generate the DID for this verifier.","enum":["did:web"]},"clientIdPrefix":{"type":"string","enum":["did_web","x509_hash","x509_san_dns"],"description":"OID4VP Client Identifier Prefix. Defaults to `did_web`."},"trustedRootCerts":{"description":"Base64-encoded X.509 root certificates trusted when verifying presented credentials.","type":"array","items":{"type":"string"}}},"required":["name"]},"Logo":{"type":"object","properties":{"uri":{"type":"string","format":"uri","description":"Publicly accessible URL of the logo image."},"altText":{"type":"string","description":"Alternative text describing the logo, used for accessibility."}},"required":["uri"]},"CreateVerifierResponse":{"type":"object","properties":{"id":{"type":"string","description":"Verifier unique ID"}},"required":["id"]}}},"paths":{"/api/v1/verifiers":{"post":{"description":"Create new Verifier","operationId":"VerifierController_createVerifier_api/v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVerifierRequest"}}}},"responses":{"201":{"description":"When Verifier is created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVerifierResponse"}}}},"400":{"description":"When the verifier name already exists."},"409":{"description":"When the Tenant already owns its maximum number of Verifiers."},"422":{"description":"When clientIdPrefix is x509_san_dns but the active access certificate carries no dNSName SAN equal to the protocol host."}},"summary":"Create Verifier","tags":["Verifier"]}}}}
```

## Get Verifier

> Get Verifier by ID

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"GetVerifierResponse":{"type":"object","properties":{"id":{"type":"string","description":"Verifier unique ID"},"name":{"type":"string","description":"Display name of the verifier."},"logo":{"description":"Logo displayed for this verifier when requesting presentations.","allOf":[{"$ref":"#/components/schemas/Logo"}]},"didMethod":{"type":"string","description":"DID method used to generate the DID for this verifier.","enum":["did:web"]},"clientIdPrefix":{"type":"string","enum":["did_web","x509_hash","x509_san_dns"],"description":"OID4VP Client Identifier Prefix this verifier presents itself with.The x509 values are backed by a request-signing certificate;`did_web` resolves the identifier through the verifier DID document."},"status":{"type":"string","description":"Current status of the verifier.","enum":["active","deactivated"]},"requiresIntendedUse":{"type":"boolean","description":"Whether this verifier attests a registered purpose. Set by registering the first intended use. While true, every presentation request must name an intended use."},"createdAt":{"format":"date-time","type":"string","description":"Date and time the verifier was created."},"trustedRootCerts":{"description":"Base64-encoded X.509 root certificates trusted when verifying presented credentials.","type":"array","items":{"type":"string"}}},"required":["id","name","didMethod","clientIdPrefix","status","requiresIntendedUse","createdAt"]},"Logo":{"type":"object","properties":{"uri":{"type":"string","format":"uri","description":"Publicly accessible URL of the logo image."},"altText":{"type":"string","description":"Alternative text describing the logo, used for accessibility."}},"required":["uri"]}}},"paths":{"/api/v1/verifiers/{id}":{"get":{"description":"Get Verifier by ID","operationId":"VerifierController_getVerifier_api/v1","parameters":[{"name":"id","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}}],"responses":{"200":{"description":"When Verifier is retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVerifierResponse"}}}},"404":{"description":"When no verifier exists with such id."}},"summary":"Get Verifier","tags":["Verifier"]}}}}
```

## Update Verifier

> Update Verifier by ID

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"UpdateVerifierRequest":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the verifier."},"logo":{"description":"Logo displayed for this verifier when requesting presentations.","allOf":[{"$ref":"#/components/schemas/Logo"}]},"clientIdPrefix":{"type":"string","enum":["did_web","x509_hash","x509_san_dns"],"description":"OID4VP Client Identifier Prefix. Switching between the two x509 values reuses the existing certificate. Under `x509_hash` the Client Identifier is the certificate hash."},"trustedRootCerts":{"description":"Base64-encoded X.509 root certificates trusted when verifying presented credentials.","type":"array","items":{"type":"string"}}},"required":["name"]},"Logo":{"type":"object","properties":{"uri":{"type":"string","format":"uri","description":"Publicly accessible URL of the logo image."},"altText":{"type":"string","description":"Alternative text describing the logo, used for accessibility."}},"required":["uri"]},"UpdateVerifierResponse":{"type":"object","properties":{"id":{"type":"string","description":"Verifier unique ID"},"name":{"type":"string","description":"Display name of the verifier."},"logo":{"description":"Logo displayed for this verifier when requesting presentations.","allOf":[{"$ref":"#/components/schemas/Logo"}]},"didMethod":{"type":"string","description":"DID method used to generate the DID for this verifier.","enum":["did:web"]},"clientIdPrefix":{"type":"string","enum":["did_web","x509_hash","x509_san_dns"],"description":"OID4VP Client Identifier Prefix this verifier presents itself with.The x509 values are backed by a request-signing certificate;`did_web` resolves the identifier through the verifier DID document."},"status":{"type":"string","description":"Current status of the verifier.","enum":["active","deactivated"]},"requiresIntendedUse":{"type":"boolean","description":"Whether this verifier attests a registered purpose. Set by registering the first intended use. While true, every presentation request must name an intended use."},"createdAt":{"format":"date-time","type":"string","description":"Date and time the verifier was created."},"trustedRootCerts":{"description":"Base64-encoded X.509 root certificates trusted when verifying presented credentials.","type":"array","items":{"type":"string"}}},"required":["id","name","didMethod","clientIdPrefix","status","requiresIntendedUse","createdAt"]}}},"paths":{"/api/v1/verifiers/{id}":{"put":{"description":"Update Verifier by ID","operationId":"VerifierController_updateVerifier_api/v1","parameters":[{"name":"id","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVerifierRequest"}}}},"responses":{"200":{"description":"When Verifier is updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVerifierResponse"}}}},"400":{"description":"When the verifier name already exists."},"404":{"description":"When no verifier exists with such id."},"409":{"description":"When clientIdPrefix is changed to did_web while the verifier still has live intended uses."},"422":{"description":"When clientIdPrefix is x509_san_dns but the active access certificate carries no dNSName SAN equal to the protocol host."}},"summary":"Update Verifier","tags":["Verifier"]}}}}
```

## Activate Verifier

> Activate Verifier by ID

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"ActivateVerifierResponse":{"type":"object","properties":{"id":{"type":"string","description":"Verifier unique ID"},"status":{"type":"string","description":"Status of the verifier after activation.","enum":["active","deactivated"]}},"required":["id","status"]}}},"paths":{"/api/v1/verifiers/{id}/activate":{"post":{"description":"Activate Verifier by ID","operationId":"VerifierController_activateVerifier_api/v1","parameters":[{"name":"id","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}}],"responses":{"200":{"description":"When Verifier is activated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateVerifierResponse"}}}},"404":{"description":"When no verifier exists with such id."}},"summary":"Activate Verifier","tags":["Verifier"]}}}}
```

## Deactivate Verifier

> Deactivate Verifier by ID

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"DeactivateVerifierResponse":{"type":"object","properties":{"id":{"type":"string","description":"Verifier unique ID"},"status":{"type":"string","description":"Status of the verifier after deactivation.","enum":["active","deactivated"]}},"required":["id","status"]}}},"paths":{"/api/v1/verifiers/{id}/deactivate":{"post":{"description":"Deactivate Verifier by ID","operationId":"VerifierController_deactivateVerifier_api/v1","parameters":[{"name":"id","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}}],"responses":{"200":{"description":"When Verifier is deactivated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeactivateVerifierResponse"}}}},"404":{"description":"When no verifier exists with such id."}},"summary":"Deactivate Verifier","tags":["Verifier"]}}}}
```

## \[Experimental] List intended uses

> Returns a page of the live intended uses registered on this Verifier, oldest first.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"GetIntendedUsesResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/GetIntendedUsesResponseItem"}},"pagination":{"$ref":"#/components/schemas/PaginationData"}},"required":["items","pagination"]},"GetIntendedUsesResponseItem":{"type":"object","properties":{"id":{"type":"string","description":"Intended use unique ID"},"registrarIdentifier":{"type":"string","description":"The Registrar's own identifier for this registration. Immutable once the intended use exists."},"purposeDescription":{"type":"string","description":"Human-readable statement of why this Verifier asks for these attributes."},"registrationCertificate":{"type":"string","description":"The Relying Party Registration Certificate as a compact JWS, byte-identical to the one supplied. Emitted to wallets in the signed request."}},"required":["id","registrarIdentifier","purposeDescription","registrationCertificate"]},"PaginationData":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"}},"required":["page","limit"]}}},"paths":{"/api/v1/verifiers/{verifierId}/intended-uses":{"get":{"description":"Returns a page of the live intended uses registered on this Verifier, oldest first.","operationId":"IntendedUseController_getIntendedUses_api/v1","parameters":[{"name":"verifierId","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"default":10,"type":"number"}}],"responses":{"200":{"description":"When a page of the Verifier's live intended uses is returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetIntendedUsesResponse"}}}},"404":{"description":"When no Verifier with that identifier exists in the caller tenant context"}},"summary":"[Experimental] List intended uses","tags":["Verifier"]}}}}
```

## \[Experimental] Register intended use

> Registers a purpose this Verifier is authorised to ask for, with the Registrar's certificate attesting it. The first registration marks the Verifier as requiring an intended use.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"CreateIntendedUseRequest":{"type":"object","properties":{"registrarIdentifier":{"type":"string","description":"The Registrar's identifier for this registration. Cannot be changed afterwards, and must be unique among this Verifier's live intended uses."},"purposeDescription":{"type":"string","description":"Why this Verifier asks for these attributes, in terms a person can read."},"registrationCertificate":{"type":"string","description":"The Relying Party Registration Certificate issued by the Registrar for this intended use, as a compact JWS. Stored verbatim, and accepted only if it authenticates against its own x5c chain, carries the claims a Wallet requires, and is bound to the active access certificate."}},"required":["registrarIdentifier","purposeDescription","registrationCertificate"]},"CreateIntendedUseResponse":{"type":"object","properties":{"id":{"type":"string","description":"Intended use unique ID"},"registrarIdentifier":{"type":"string","description":"The Registrar's own identifier for this registration. Immutable once the intended use exists."},"purposeDescription":{"type":"string","description":"Human-readable statement of why this Verifier asks for these attributes."},"registrationCertificate":{"type":"string","description":"The Relying Party Registration Certificate as a compact JWS, byte-identical to the one supplied. Emitted to wallets in the signed request."}},"required":["id","registrarIdentifier","purposeDescription","registrationCertificate"]}}},"paths":{"/api/v1/verifiers/{verifierId}/intended-uses":{"post":{"description":"Registers a purpose this Verifier is authorised to ask for, with the Registrar's certificate attesting it. The first registration marks the Verifier as requiring an intended use.","operationId":"IntendedUseController_createIntendedUse_api/v1","parameters":[{"name":"verifierId","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIntendedUseRequest"}}}},"responses":{"201":{"description":"When the intended use is registered. The Verifier is marked as requiring an intended use from this point, so its x509 presentation requests must select one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIntendedUseResponse"}}}},"404":{"description":"When no Verifier with that identifier exists in the caller tenant context"},"409":{"description":"When an intended use with that registrar-assigned identifier is already live on this Verifier"},"422":{"description":"When the registration certificate cannot be authenticated (not a compact JWS of type rc-wrp+jwt, no x5c chain, or a signature that does not verify against the x5c leaf), when a claim a Wallet requires is missing or elapsed (entitlements, status.status_list, exp/nbf), or when it is bound to an entity other than the one the active access certificate identifies, or when the Verifier uses the did_web Client Identifier Prefix, which carries no verifier_info and so cannot attest a registered purpose"}},"summary":"[Experimental] Register intended use","tags":["Verifier"]}}}}
```

## \[Experimental] Get intended use

> Returns one intended use and the registration certificate stored for it.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"GetIntendedUseResponse":{"type":"object","properties":{"id":{"type":"string","description":"Intended use unique ID"},"registrarIdentifier":{"type":"string","description":"The Registrar's own identifier for this registration. Immutable once the intended use exists."},"purposeDescription":{"type":"string","description":"Human-readable statement of why this Verifier asks for these attributes."},"registrationCertificate":{"type":"string","description":"The Relying Party Registration Certificate as a compact JWS, byte-identical to the one supplied. Emitted to wallets in the signed request."}},"required":["id","registrarIdentifier","purposeDescription","registrationCertificate"]}}},"paths":{"/api/v1/verifiers/{verifierId}/intended-uses/{id}":{"get":{"description":"Returns one intended use and the registration certificate stored for it.","operationId":"IntendedUseController_getIntendedUse_api/v1","parameters":[{"name":"verifierId","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Intended use unique ID","schema":{"type":"string"}}],"responses":{"200":{"description":"When the intended use is returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetIntendedUseResponse"}}}},"404":{"description":"When no Verifier with that identifier exists in the caller tenant context, or when the intended use does not exist on it or has been deleted"}},"summary":"[Experimental] Get intended use","tags":["Verifier"]}}}}
```

## \[Experimental] Update intended use

> Replaces the purpose description, the registration certificate, or both. The registrar-assigned identifier is immutable.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"UpdateIntendedUseRequest":{"type":"object","properties":{"purposeDescription":{"type":"string","description":"Replacement purpose description."},"registrationCertificate":{"type":"string","description":"Replacement registration certificate, as a compact JWS. Re-runs every storage validation and replaces the stored certificate in the same operation."}}},"UpdateIntendedUseResponse":{"type":"object","properties":{"id":{"type":"string","description":"Intended use unique ID"},"registrarIdentifier":{"type":"string","description":"The Registrar's own identifier for this registration. Immutable once the intended use exists."},"purposeDescription":{"type":"string","description":"Human-readable statement of why this Verifier asks for these attributes."},"registrationCertificate":{"type":"string","description":"The Relying Party Registration Certificate as a compact JWS, byte-identical to the one supplied. Emitted to wallets in the signed request."}},"required":["id","registrarIdentifier","purposeDescription","registrationCertificate"]}}},"paths":{"/api/v1/verifiers/{verifierId}/intended-uses/{id}":{"put":{"description":"Replaces the purpose description, the registration certificate, or both. The registrar-assigned identifier is immutable.","operationId":"IntendedUseController_updateIntendedUse_api/v1","parameters":[{"name":"verifierId","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Intended use unique ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIntendedUseRequest"}}}},"responses":{"200":{"description":"When the intended use is updated. A replaced certificate is stored in the same operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIntendedUseResponse"}}}},"404":{"description":"When no Verifier with that identifier exists in the caller tenant context, or when the intended use does not exist on it or has been deleted"},"422":{"description":"When the registration certificate cannot be authenticated (not a compact JWS of type rc-wrp+jwt, no x5c chain, or a signature that does not verify against the x5c leaf), when a claim a Wallet requires is missing or elapsed (entitlements, status.status_list, exp/nbf), or when it is bound to an entity other than the one the active access certificate identifies"}},"summary":"[Experimental] Update intended use","tags":["Verifier"]}}}}
```

## \[Experimental] Delete intended use

> Soft-deletes the intended use. This does not stop the Verifier having to attest a purpose: deleting the last one fails its x509 requests closed. Use the clear-requirement action to stop attesting.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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."}}},"paths":{"/api/v1/verifiers/{verifierId}/intended-uses/{id}":{"delete":{"description":"Soft-deletes the intended use. This does not stop the Verifier having to attest a purpose: deleting the last one fails its x509 requests closed. Use the clear-requirement action to stop attesting.","operationId":"IntendedUseController_deleteIntendedUse_api/v1","parameters":[{"name":"verifierId","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Intended use unique ID","schema":{"type":"string"}}],"responses":{"204":{"description":"When the intended use is soft-deleted. The Verifier's requires-an-intended-use mark is deliberately unchanged, so deleting the last one fails its x509 requests closed rather than reverting them to carrying no purpose"},"404":{"description":"When no Verifier with that identifier exists in the caller tenant context, or when the intended use does not exist on it or has been deleted"}},"summary":"[Experimental] Delete intended use","tags":["Verifier"]}}}}
```

## \[Experimental] Stop attesting a purpose

> Clears the requires-an-intended-use mark, letting this Verifier issue x509 presentation requests that carry no registration certificate again. A deliberate downgrade in what it tells wallets, and logged as one.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"ClearIntendedUseRequirementResponse":{"type":"object","properties":{"verifierId":{"type":"string","description":"Verifier unique ID"},"wasRequired":{"type":"boolean","description":"Whether the Verifier had been attesting a purpose before this call. False means the call changed nothing."}},"required":["verifierId","wasRequired"]}}},"paths":{"/api/v1/verifiers/{verifierId}/intended-uses/clear-requirement":{"post":{"description":"Clears the requires-an-intended-use mark, letting this Verifier issue x509 presentation requests that carry no registration certificate again. A deliberate downgrade in what it tells wallets, and logged as one.","operationId":"IntendedUseController_clearIntendedUseRequirement_api/v1","parameters":[{"name":"verifierId","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}}],"responses":{"200":{"description":"When the Verifier no longer has to attest a purpose. This is a downgrade in what it tells wallets and is logged as one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClearIntendedUseRequirementResponse"}}}},"404":{"description":"When no Verifier with that identifier exists in the caller tenant context"}},"summary":"[Experimental] Stop attesting a purpose","tags":["Verifier"]}}}}
```

## Get VP Schemas

> Get paginated VP Schemas

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"GetVpSchemasResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/VpSchemaResponseItem"}},"pagination":{"$ref":"#/components/schemas/PaginationData"}},"required":["items","pagination"]},"VpSchemaResponseItem":{"type":"object","properties":{"id":{"type":"string","description":"VP schema unique ID"},"name":{"type":"string","description":"Display name of the VP schema."},"description":{"type":"object","description":"Human-readable description of the VP schema."},"verifiers":{"description":"Identifiers of the verifiers to use this VP schema.","type":"array","items":{"type":"string"}},"inputs":{"description":"Inputs describing the credentials and claims requested by this VP schema.","type":"array","items":{"$ref":"#/components/schemas/VpSchemaInput"}},"used":{"type":"boolean","description":"Determines whether the VP schema has already been used in presentation flow.","default":false},"createdAt":{"format":"date-time","type":"string","description":"Date and time the VP schema was created."}},"required":["id","name","verifiers","inputs","used","createdAt"]},"VpSchemaInput":{"type":"object","properties":{"vcSchemaVersionIds":{"description":"VC schema version identifiers this input can be satisfied by.","type":"array","items":{"type":"string"}},"credTypes":{"description":"Credential type this input can be satisfied by, as an alternative to vcSchemaVersionIds.","allOf":[{"$ref":"#/components/schemas/VpSchemaInputCredType"}]},"claims":{"description":"Claims requested from the presented credential.","type":"array","items":{"$ref":"#/components/schemas/VpSchemaInputClaims"}},"fullDisclosure":{"type":"boolean","description":"Determines whether all claims of the credential must be disclosed."}}},"VpSchemaInputCredType":{"type":"object","properties":{"format":{"type":"string","description":"Credential format the queried credential type values belong to."},"values":{"description":"Credential type identifiers accepted for this input.","type":"array","items":{"type":"string"}}},"required":["format","values"]},"VpSchemaInputClaims":{"type":"object","properties":{"path":{"description":"Path of the claim to disclose within the credential.","type":"array","items":{"type":"string"}},"values":{"description":"Allowed values the claim must match. If omitted any value of the claim is accepted.","type":"array","items":{"type":"string"}},"mandatory":{"type":"boolean","description":"Determines whether the claim must be disclosed by the holder."}},"required":["path"]},"PaginationData":{"type":"object","properties":{"page":{"type":"number"},"limit":{"type":"number"}},"required":["page","limit"]}}},"paths":{"/api/v1/vp-schemas":{"get":{"description":"Get paginated VP Schemas","operationId":"VpSchemaController_getVpSchemas_api/v1","parameters":[{"name":"page","required":false,"in":"query","schema":{"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"default":10,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by","schema":{"default":"date","type":"string","enum":["name","date"]}},{"name":"order","required":false,"in":"query","description":"Sort direction","schema":{"default":"asc","type":"string","enum":["asc","desc"]}},{"name":"verifierId","required":false,"in":"query","description":"Verifier unique ID","schema":{"type":"string"}}],"responses":{"200":{"description":"When VP Schemas are retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVpSchemasResponse"}}}}},"summary":"Get VP Schemas","tags":["Verifier"]}}}}
```

## Create VP Schema

> Create new VP Schema

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"CreateVpSchemaRequest":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the VP schema."},"description":{"type":"string","description":"Human-readable description of the VP schema."},"verifiers":{"description":"Identifiers of the verifiers allowed to use this VP schema.","type":"array","items":{"type":"string"}},"inputs":{"description":"Inputs describing the credentials and claims requested by this VP schema.","type":"array","items":{"$ref":"#/components/schemas/VpSchemaInput"}}},"required":["name","verifiers","inputs"]},"VpSchemaInput":{"type":"object","properties":{"vcSchemaVersionIds":{"description":"VC schema version identifiers this input can be satisfied by.","type":"array","items":{"type":"string"}},"credTypes":{"description":"Credential type this input can be satisfied by, as an alternative to vcSchemaVersionIds.","allOf":[{"$ref":"#/components/schemas/VpSchemaInputCredType"}]},"claims":{"description":"Claims requested from the presented credential.","type":"array","items":{"$ref":"#/components/schemas/VpSchemaInputClaims"}},"fullDisclosure":{"type":"boolean","description":"Determines whether all claims of the credential must be disclosed."}}},"VpSchemaInputCredType":{"type":"object","properties":{"format":{"type":"string","description":"Credential format the queried credential type values belong to."},"values":{"description":"Credential type identifiers accepted for this input.","type":"array","items":{"type":"string"}}},"required":["format","values"]},"VpSchemaInputClaims":{"type":"object","properties":{"path":{"description":"Path of the claim to disclose within the credential.","type":"array","items":{"type":"string"}},"values":{"description":"Allowed values the claim must match. If omitted any value of the claim is accepted.","type":"array","items":{"type":"string"}},"mandatory":{"type":"boolean","description":"Determines whether the claim must be disclosed by the holder."}},"required":["path"]},"CreateVpSchemaResponse":{"type":"object","properties":{"id":{"type":"string","description":"VP schema unique ID"}},"required":["id"]}}},"paths":{"/api/v1/vp-schemas":{"post":{"description":"Create new VP Schema","operationId":"VpSchemaController_createVpSchema_api/v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVpSchemaRequest"}}}},"responses":{"201":{"description":"When VP Schema is created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVpSchemaResponse"}}}},"400":{"description":"- When one or more inputs contain invalid data.\n- When one or more Verifier IDs do not exist.\n- When one or more Verifiers are inactive.\n- When one or more VC Schema IDs do not exist.\n- When the VP Schema name already exists."}},"summary":"Create VP Schema","tags":["Verifier"]}}}}
```

## Get VP Schema

> Get VP Schema by ID

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"GetVpSchemaResponse":{"type":"object","properties":{"id":{"type":"string","description":"VP schema unique ID"},"name":{"type":"string","description":"Display name of the VP schema."},"description":{"type":"object","description":"Human-readable description of the VP schema."},"verifiers":{"description":"Identifiers of the verifiers to use this VP schema.","type":"array","items":{"type":"string"}},"inputs":{"description":"Inputs describing the credentials and claims requested by this VP schema.","type":"array","items":{"$ref":"#/components/schemas/VpSchemaInput"}},"used":{"type":"boolean","description":"Determines whether the VP schema has already been used in presentation flow.","default":false},"createdAt":{"format":"date-time","type":"string","description":"Date and time the VP schema was created."}},"required":["id","name","verifiers","inputs","used","createdAt"]},"VpSchemaInput":{"type":"object","properties":{"vcSchemaVersionIds":{"description":"VC schema version identifiers this input can be satisfied by.","type":"array","items":{"type":"string"}},"credTypes":{"description":"Credential type this input can be satisfied by, as an alternative to vcSchemaVersionIds.","allOf":[{"$ref":"#/components/schemas/VpSchemaInputCredType"}]},"claims":{"description":"Claims requested from the presented credential.","type":"array","items":{"$ref":"#/components/schemas/VpSchemaInputClaims"}},"fullDisclosure":{"type":"boolean","description":"Determines whether all claims of the credential must be disclosed."}}},"VpSchemaInputCredType":{"type":"object","properties":{"format":{"type":"string","description":"Credential format the queried credential type values belong to."},"values":{"description":"Credential type identifiers accepted for this input.","type":"array","items":{"type":"string"}}},"required":["format","values"]},"VpSchemaInputClaims":{"type":"object","properties":{"path":{"description":"Path of the claim to disclose within the credential.","type":"array","items":{"type":"string"}},"values":{"description":"Allowed values the claim must match. If omitted any value of the claim is accepted.","type":"array","items":{"type":"string"}},"mandatory":{"type":"boolean","description":"Determines whether the claim must be disclosed by the holder."}},"required":["path"]}}},"paths":{"/api/v1/vp-schemas/{uuid}":{"get":{"description":"Get VP Schema by ID","operationId":"VpSchemaController_getVpSchema_api/v1","parameters":[{"name":"uuid","required":true,"in":"path","description":"VP schema unique ID","schema":{"type":"string"}}],"responses":{"200":{"description":"When VP Schema is retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetVpSchemaResponse"}}}},"404":{"description":"When no VP Schema exists with such id."}},"summary":"Get VP Schema","tags":["Verifier"]}}}}
```

## Update VP Schema

> Update VP Schema by ID

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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":{"UpdateVpSchemaRequest":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the VP schema."},"description":{"type":"string","description":"Human-readable description of the VP schema."},"inputs":{"description":"Inputs describing the credentials and claims requested by this VP schema.","type":"array","items":{"$ref":"#/components/schemas/VpSchemaInput"}}},"required":["name","inputs"]},"VpSchemaInput":{"type":"object","properties":{"vcSchemaVersionIds":{"description":"VC schema version identifiers this input can be satisfied by.","type":"array","items":{"type":"string"}},"credTypes":{"description":"Credential type this input can be satisfied by, as an alternative to vcSchemaVersionIds.","allOf":[{"$ref":"#/components/schemas/VpSchemaInputCredType"}]},"claims":{"description":"Claims requested from the presented credential.","type":"array","items":{"$ref":"#/components/schemas/VpSchemaInputClaims"}},"fullDisclosure":{"type":"boolean","description":"Determines whether all claims of the credential must be disclosed."}}},"VpSchemaInputCredType":{"type":"object","properties":{"format":{"type":"string","description":"Credential format the queried credential type values belong to."},"values":{"description":"Credential type identifiers accepted for this input.","type":"array","items":{"type":"string"}}},"required":["format","values"]},"VpSchemaInputClaims":{"type":"object","properties":{"path":{"description":"Path of the claim to disclose within the credential.","type":"array","items":{"type":"string"}},"values":{"description":"Allowed values the claim must match. If omitted any value of the claim is accepted.","type":"array","items":{"type":"string"}},"mandatory":{"type":"boolean","description":"Determines whether the claim must be disclosed by the holder."}},"required":["path"]},"UpdateVpSchemaResponse":{"type":"object","properties":{"id":{"type":"string","description":"VP schema unique ID"},"name":{"type":"string","description":"Display name of the VP schema."},"description":{"type":"object","description":"Human-readable description of the VP schema."},"verifiers":{"description":"Identifiers of the verifiers to use this VP schema.","type":"array","items":{"type":"string"}},"inputs":{"description":"Inputs describing the credentials and claims requested by this VP schema.","type":"array","items":{"$ref":"#/components/schemas/VpSchemaInput"}},"used":{"type":"boolean","description":"Determines whether the VP schema has already been used in presentation flow.","default":false},"createdAt":{"format":"date-time","type":"string","description":"Date and time the VP schema was created."}},"required":["id","name","verifiers","inputs","used","createdAt"]}}},"paths":{"/api/v1/vp-schemas/{uuid}":{"put":{"description":"Update VP Schema by ID","operationId":"VpSchemaController_updateVpSchema_api/v1","parameters":[{"name":"uuid","required":true,"in":"path","description":"VP schema unique ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVpSchemaRequest"}}}},"responses":{"200":{"description":"When VP Schema is updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVpSchemaResponse"}}}},"400":{"description":"- When one or more inputs contain invalid data.\n- When one or more VC Schema IDs do not exist.\n- When the VP Schema name already exists."},"404":{"description":"When no VP Schema exists with such id."},"409":{"description":"When VP Schema cannot be altered as it is in use."}},"summary":"Update VP Schema","tags":["Verifier"]}}}}
```

## Delete VP Schema

> Delete VP Schema by ID

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Control API Documentation","version":"0.1.2"},"tags":[{"name":"Verifier","description":""}],"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."}}},"paths":{"/api/v1/vp-schemas/{uuid}":{"delete":{"description":"Delete VP Schema by ID","operationId":"VpSchemaController_deleteVpSchema_api/v1","parameters":[{"name":"uuid","required":true,"in":"path","description":"VP schema unique ID","schema":{"type":"string"}}],"responses":{"200":{"description":"When VP Schema is deleted successfully."},"404":{"description":"When no VP Schema exists with such id."},"409":{"description":"When VP Schema cannot be altered as it is in use."}},"summary":"Delete VP Schema","tags":["Verifier"]}}}}
```


---

# 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/verifier.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.