Skip to Content
API and DashboardCertificates

Certificates

Paradym enables you to use X.509 certificates to authenticate OpenID4VC presentation requests, and, in the future, to issue credentials. To do so, you can create a root certificate for the specific use case. The root certificate is then used to automatically generate leaf certificates, which are used for the actual signing of the requests and the credentials.

Creating a Certificate

When creating a certificate, you need to provide the following information:

  • The type of the root certificate to create. At the moment, it is only possible to create verifier root certificates to authenticate OpenID4VP presentation requests.
  • The type of the Private Key used to sign the root certificate. You are only allowed to have a single active certificate of each key type and certificate type combination, at a single point in time.
  • The ISO 3166-1 2-letter country code of the country where the issuer is located, and, optionally, a human-readable common name, identifying the issuer.
  • The issuer alternative name, which is the URL that identifies the issuer.

By default, the root certificate has a validity of 5 years. If you need to renew it beforehand because, for example, your details have changed, you can create a new certificate, and activate it. This will automatically deactivate the old one.

To create a certificate from the API, make a POST request to https://api.paradym.id/v1/projects/{projectId}/certificates. See the API Reference for detailed usage information.

{ "type": "verifierRoot", "keyType": "P-256", "countryName": "NL", "commonName": "Example Company BV", "issuerAlternativeNameUrl": "https://example.com" }

Activate a Certificate

If you have a certificate of a certain certificate type and key type combination and create a new one, the new one will be “pending activation”. This means that the new certificate won’t be used until it is activated. That happens automatically when the currently active one expires.

However, you can manually activate the new one, which automatically deactivates the old one. This can be useful when you want to update information contained in the certificate, or during renewal, if you have already shared the new certificate with all relevant parties and want to start using the new one immediately.

To activate a certificate from the API, make a POST request to https://api.paradym.id/v1/projects/{projectId}/certificates/{certificateId}/activate. See the API Reference for detailed usage information.

Revoking a Certificate

Revoking a certificate should be done if the certificate is compromised. This can be easily done via the dashboard or the API. Afterwards, the certificate will be pending revocation. Once the Certificate Revocation List has been updated, the certificate status will change to revoked.

Note that revoking a certificate is an irreversible operation. In addition, if you revoke a root certificate, we will automatically revoke all its children certificates.

To revoke a certificate from the API, make a POST request to https://api.paradym.id/v1/projects/{projectId}/certificates/{certificateId}/revoke. See the API Reference for detailed usage information.

Presentation Templates

You can use the certificates to authenticate presentation requests. To do so, you first need to create a certificate, as described above. Then, you need to create a Presentation Template as described in the documentation. In that page, you can choose the authentication method, which, by default, will be did:web. You can also choose to use any of the available X.509 certificates.

Last updated on