This page provides a step-by-step guide on how to use the available API endpoints. For the full API specification please refer to the Swagger documentation available at:
/apidocs/
This guide provides a practical overview of the available API endpoints and demonstrates how they can be used. The endpoints described in this guide are generally independent and do not require a strict execution order. Each endpoint can be used individually as long as its required parameters and conditions are satisfied. Some endpoints are designed to complement others and may typically be used together as part of a broader workflow. Nevertheless, any endpoint can be executed independently, provided that its specific requirements are fulfilled.
To start using the service, you must first register a user.
Go to:
https://dev.registry.serviceproviders.eudiw.dev/authentication
This endpoint will initiate the authentication process and return a JSON response containing:
{
"QR_code_url": "https://example.com/qr/123456",
"presentation_id": "550e8400-e29b-41d4-a716-446655440000"
}
Notes:
- The QR_code_url should be used to display the QR code to the user for authentication.
- The presentation_id is required for the next steps of the authentication flow.
After receiving the presentation_id from Step 1, you must call the following endpoint:
/pid_authorization
This request must include the presentation_id as a query parameter.
Example request:
/pid_authorization?presentation_id=<presentation_id from step 1>
You must wait until the authentication process is completed successfully. Once successful, the endpoint will return:
{
"message": {
"message": "Sucess"
}
}
Only after receiving this response should you proceed to the next step.
After successful authorization in Step 2, you must call the following endpoint:
/getpidoid4vp
This request must include the presentation_id as a query parameter, just like in the previous step.
Example request:
/getpidoid4vp?presentation_id=<presentation_id from step 1>
If everything is successful, the endpoint will return the hash_pid:
abc123hashpid
Notes:
- The hash_pid is required for all subsequent endpoints.
- You should store this value securely, as it represents the authenticated user.
Once you have your hash_pid, you can start using all available endpoints. The first step is to create a person, which can either be a Natural Person or a Legal Person, each with its own specific attributes.
{
"birthdate": "1990-01-01",
"birthplace": "Lisbon",
"family_name": "Doe",
"given_name": "John",
"hash_pid": "<hash_pid from step 1>"
}
Once the request is successfully processed, you will receive the response message: "Natural Person successfully created."
Use the endpoint /legal_person/add_legal_person_db to create a Legal Person.
Send the following JSON in the request body:
{
"established_by_law": "Commercial Law Article 10",
"hash_pid": "<hash_pid from step 1>",
"lang": "EN",
"legal_name": "ACME Corporation"
}
Once the request is successfully processed, you will receive the response message: "Legal Person successfully created."
Use the endpoint /legal_entity/add_legal_entity_db to create a Legal Entity. Send the following JSON in the request body:
{
"address": "123 Main Street, City, Country",
"country": "EU",
"email": "contact@acme.com",
"hash_pid": "<hash_pid from step 1>",
"identifier": "123456789",
"information_URI": "https://acme.com/info",
"phone_number": "+123456789",
"type_of_identifier": "http://data.europa.eu/eudi/id/EORI-No"
}
Once the request is successfully processed, you will receive the response message: "Legal Entity successfully created."
Now that you have created your Natural Persons or Legal Persons and Legal Entities, the next step is to list them and prepare for establishing relationships.
For both endpoints, the body of the request should be a JSON containing your hash_pid from Step 1:
{
"hash_pid": "<hash_pid from step 1>"
}
Use the endpoint /natural_person/list to view all Natural Persons and all available Legal Entities.
When reviewing the list, pay special attention to:
Note that a Legal Entity may already be associated with another Natural Person.
If you associate a Legal Entity that already has its associated field set to True, the previous association will be replaced with the new one.
Use the endpoint /legal_person/list to view all Legal Persons and all available Legal Entities.
When reviewing the list, pay special attention to:
Similarly, if a Legal Entity is already associated with another Legal Person, assigning it to a new Legal Person will replace the previous association.
After listing your Natural Persons, Legal Persons and Legal Entities in Step 4, the next step is to establish associations between them.
You can associate either a Legal Person or a Natural Person with one or more Legal Entities.
To associate a Natural Person with Legal Entities, use the endpoint /natural_person/ui_update_legal_entities.
Example JSON body:
{
"hash_pid": "<hash_pid from step 1>",
"natural_person": 1,
"legal_entities_ids": [1]
}
Note that legal_entities_ids must always be an array [], even if you are associating only one Legal Entity.
To associate multiple Legal Entities with a Natural Person, include all their IDs inside the array, separated by commas, like this:
"legal_entities_ids": [1, 2, 3, 4]
If the association is successful, you will receive the message:
"Associations updated successfully".
To associate a Legal Person with Legal Entities, use the endpoint /legal_person/ui_update_legal_entities.
Example JSON body:
{
"hash_pid": "<hash_pid from step 1>",
"legal_person": 1,
"legal_entities_ids": [1]
}
Just like with Natural Persons, the legal_entities_ids field must be an array.
To associate multiple Legal Entities with a Legal Person, include all IDs inside the array, separated by commas:
"legal_entities_ids": [1, 2, 3, 4]
If the association is successful, you will receive the message:
"Associations updated successfully".
This endpoint allows you to create a Relying Party that can later be associated with a Legal Entity.
To create a Relying Party, use the endpoint /RP/add_RP_db.
Example JSON body:
{
"hash_pid": "<hash_pid from step 1>",
"trade_name": "ACME RP Services",
"srvDescription": "Provides authentication services for ACME users.",
"srvDescription_lang": "EU",
"entitlement": "http://data.europa.eu/eudi/entitlement/Service_Provider",
"type_of_policy": "http://data.europa.eu/eudi/policy/trust-service-practice-statement",
"policy_uri": "https://acme.com/policy",
"registry_uri": "https://registry.acme.com",
"support_URI": "https://acme.com/support",
"x5c": "MIID...AB"
}
If the request is successful, you will receive the message:
"Relying Party successfully created."
Now that you have created your Legal Entities and Relying Parties, the next step is to list them and prepare for establishing relationships.
The body of the request should be a JSON containing your hash_pid from Step 1:
{
"hash_pid": "<hash_pid from step 1>"
}
Use the endpoint /legal_entity/list to view all Legal Entities and all available Relying Parties.
When reviewing the list, pay special attention to:
Note that a Relying Party may already be associated with another Legal Entity.
If you associate a Relying Party that already has its associated field set to True, the previous association will be replaced with the new one.
After listing your Legal Entities and Relying Parties in the previous step, you can now establish associations between them.
To associate one or more Relying Parties with a Legal Entity, use the endpoint /legal_entity/ui_update_RPs.
Example JSON body:
{
"hash_pid": "<hash_pid from step 1>",
"legal_entity": 1,
"relying_parties": [1]
}
Note that:
[], even if you are associating only one Relying PartyTo associate multiple Relying Parties with the same Legal Entity, include all their IDs inside the array, separated by commas:
"relying_parties": [1, 2, 3, 4]
If the association is successful, you will receive the message:
"Associations updated successfully".
You can now create an Intended Use, which defines how data or services may be used within the system.
To create an Intended Use, use the endpoint /intended_use/add_intended_use_db.
The body of the request must be a JSON object with the following parameters:
{
"hash_pid": "<hash_pid from step 1>",
"intendedUseIdentifier": "intended_use_001",
"purpose": "Data processing for analytics",
"purpose_lang": "EU",
"policy_uri": "https://acme.com/privacy-policy",
"type_policy": "http://data.europa.eu/eudi/policy/trust-service-practice-statement",
"createAt": "2026-02-09 12:00:00",
"revokeAt": "2026-12-31 23:59:59"
}
If the request is successful, you will receive the message:
"Intended Use successfully created."
Before creating associations between Relying Parties and Intended Uses, it is recommended to list the existing Relying Parties to understand their current status and relationships.
Use the endpoint /RP/list to retrieve all Relying Parties, including information about which Intended Uses are already associated.
The body of the request must be a JSON containing your hash_pid from Step 1:
{
"hash_pid": "<hash_pid from step 1>"
}
When reviewing the response, pay special attention to:
Note that a Intended Uses may already be associated with another Relying Party.
If you associate a Intended Uses that already has its associated field set to True, the previous association will be replaced with the new one.
After listing your Relying Parties and Intended Uses, you can now establish associations between them.
To associate Intended Uses with a Relying Party, use the endpoint /RP/ui_update_intended_use.
The body of the request must be a JSON containing:
{
"hash_pid": "<hash_pid from step 1>",
"relying_party": 1,
"intended_uses": [1]
}
Important rules:
[], even if only one Intended Use is providedTo associate multiple Intended Uses with the same Relying Party, include all IDs inside the array, separated by commas:
"intended_uses": [1, 2, 3, 4]
If the association is successful, you will receive the message:
"Associations updated successfully".
In this endpoint, you can create new credentials using /credential/add_credential_db.
The body of the request should be a JSON like this:
{
"hash_pid": "<hash_pid from step 1>",
"name": "Credential name",
"path": "/credentials/cred.json",
"format": "JSON",
"credentialValues": "credentialValues",
"meta": "meta"
}
If the creation is successful, the response will be:
"Credential successfully created."
After creating credentials, you can list all Intended Uses and see which credentials they are associated with using the endpoint /intended_use/list.
The body of the request should be a JSON containing your hash_pid from Step 1:
{
"hash_pid": "<hash_pid from step 1>"
}
Note that an Intended Uses may already be associated with one or more credential.
If you associate a Intended Use with a credential that already has its associated field set to True, the previous association will be replaced with the new one.
After listing your Intended Uses and the available credentials in Step 13, you can associate an Intended Use with one or more credential using the endpoint /intended_use/ui_update_intended_uses.
Example JSON body:
{
"hash_pid": "<hash_pid from step 1>",
"credentials": [1],
"intended_use": 1
}
Notes:
- Only one Intended Use can be specified in the intended_use field.
- The credential field must always be an array [], even if you are associating only one credential.
- To associate multiple credentials with an Intended Uses, include all IDs inside the array, separated by commas, like this:
"credentials": [1, 2, 3, 4]
If the association is successful, you will receive the message:
"Associations updated successfully".
After creating and configuring your Relying Parties, you can retrieve the certificate associated with a specific Relying Party using the endpoint /RP/certificate.
This endpoint returns the generated certificate file associated with the selected Relying Party.
Example JSON body:
{
"hash_pid": "<hash_pid from step 1>",
"relying_party": 1,
"password": "example-password"
}
Notes:
- Only one Relying Party can be specified in the relying_party field.
- The provided Relying Party must belong to the authenticated user.
- If the request is successful, the certificate file associated with the Relying Party will be returned.
You can also retrieve the certificate generated for a specific Intended Use using the endpoint /intended_use/certificate.
This endpoint returns the generated document and its corresponding COSE signature encoded in Base64.
Example JSON body:
{
"hash_pid": "<hash_pid from step 1>",
"intended_use": 1
}
If the request is successful, the response will contain:
{
"status": "success",
"code": 200,
"data": {
"filename": "document_with_signature.json",
"file_base64": "...",
"cose_base64": "..."
}
}
Notes:
- Only one Intended Use can be specified in the intended_use field.
- The provided Intended Use must belong to the authenticated user.
- The file_base64 field contains the generated document encoded in Base64.
- The cose_base64 field contains the COSE signature of the document.