Frequently asked questions and troubleshooting for Registration Authority (RA) integrators and operators. Short answers are given below; for more integration details, see Developer documentation and Get started.
Use the secure_element parameter in your request to indicate where the certificate will be stored:
| Value | Meaning |
|---|---|
| 0 | Software — Certificate stored in software. |
| 1 | Smartcard — Certificate stored on a smartcard. |
| 2 | Cloud — Certificate stored in the cloud. |
Set secure_element accordingly when creating or updating a request (e.g. in Create Request or Update Request). See the OpenAPI specification for the exact parameter in each operation.
Use the Registration Authority (RA) id that has been provided to you by your commercial contact or Operations, or the one included in the dataset you received to use the service. You need this id in the registration_authority field when creating requests. See Get started; if you do not have it, contact your commercial contact or Operations directly.
Use the certificate profile that has been assigned to your use case by your commercial contact or Operations (or the one indicated in the dataset or contract you received). The profile determines which fields are required, the type of certificate, and the allowed validity_time and secure_element options. If you are unsure, contact your commercial contact or Operations directly to confirm the correct profile for your RA and certificate type.
For Create Request (POST /api/v1/requests/), the required fields in the request body include at least:
- profile — Certificate profile.
- registration_authority — RA id (assigned to you).
- scratchcard — Serial number of an available, unused scratchcard.
- email — Subscriber email.
- given_name — Subscriber given name.
- surname_1 (and surname_2 where applicable) — Subscriber surname(s).
- id_document_type — Document type.
- mobile_phone_number — Mobile number (international format).
- validity_time — Certificate validity (in days).
- secure_element — 0 (Software), 1 (Smartcard), or 2 (Cloud).
Depending on the certificate profile, additional fields may be mandatory. Check the Create Request schema and the Certificate Profiles section in the OpenAPI specification for the full list per profile.
validity_time is the certificate validity period, expressed in days (e.g. 365, 730). The allowed values depend on the certificate profile you are using. Each profile may support different validity ranges. Check the OpenAPI specification for the profile you use, or contact your commercial contact or Operations directly for the exact values allowed for your RA and profile.
Yes. The mobile number must be in international format, including the country prefix (e.g. +34 for Spain, +39 for Italy). Example: +34600112233. Use this format in fields such as mobile_phone_number when creating or updating requests. See the Create Request examples in the OpenAPI specification.
Each certificate profile has its own set of allowed and required fields. The list of fields per profile is documented in the Certificate Profiles section of the Registration Authority OpenAPI specification. The Create Request operation also references this section. Open the OpenAPI spec and look for the Certificate Profiles section to see the exact fields for your profile. If the documentation is unclear for your profile, contact your commercial contact or Operations directly.
The 500 error related to certificates is usually due to one of the following:
- The certificates are malformed or do not follow the naming convention required for the certificate.
- The certificates are expired or invalid.
- You are using a Registration Authority (RA) to which those certificates do not belong.
Check the certificate format, naming, validity, and that they correspond to the RA you are using. If the problem persists, contact your commercial contact or Operations directly with the request id and error details (without exposing secrets).
For more integration details, see Developer documentation and Get started.