Acquiring Credentials for a Web Service User¶
Introduction¶
This document is intended for Economic Operators involved in the EU Deforestation Regulation having an IT system which manages electronically their statements (Due Diligence Statements or Simplified Declarations) and willing to develop the interconnection with the central EUDR system to submit the information in an automated manner. It is also intended for public institutions or private companies willing to develop software to service Economic Operators' needs in submitting information to the central EUDR system. This includes the information exchange introduced by the EUDR Amendment Regulation (2025/2650).
Acquiring Credentials for a Web Service User¶
Creation of an operator and a user in EUDR¶
The participant needs to manually create the "Operator" corresponding to the company to be registered in the system or join an existing one.
Details on this process can be found in the EUDR user guide which can be accessed through this link: Deforestation Regulation Implementation
For every Operator, at least one user must also be created. That first user will be the reference (administrator) user, which will be recorded as the "responsible person" in the operator. It cannot be an anonymous or fictional account.
Alternatively, if the operator entry already exists, the web service user can request and join this operator instead of creating a new one.
Warning
Web Service users cannot belong to more than one Operator entity.
Request and get authorization for the Web Service user¶
Once the Operator is created and validated, and user successfully joined, proceed to acquire a "web service user" and an authentication key:
Recommended approach
Complete the credential setup and test your integration in the acceptance environment first. Once connectivity and authentication are verified, repeat the process for the production environment.
1. Get the username of the EU Login account¶
To locate the username, follow the next steps:
- Log in to the EUDR Information System,
- Click in the top-right corner of the screen,
- In the Popup, click on "Edit Profile":
- In the right box "Personal Information" there is an attribute "username". This value can now be used within your system for later tasks.
2. Get the "Authentication key" for the Participant's system¶
- Go back to the page "Edit your profile",
- Scroll to the section "Web Services Access",
- If the previous steps have been completed successfully, the button "Active" should appear in this Section. Click on this Button. The section will contain a new field labeled "Authentication Key". Click the "eye" next to the field to see the value. This value can now be used within the procedure described in later tasks.
Authentication Key is Private
The Authentication Key is private and should only be used with your application. The person identified by the EU Login user that was created in the first step is responsible for the data that shall be submitted into EUDR.
Multi-Operator Setup (BodyIdentity Header)¶
If your organisation operates multiple operators under a single API user account, or if a service provider submits declarations on behalf of several operators, a Web Service Access Identifier must be assigned to each operator. This identifier is then included in the BodyIdentity SOAP header to specify which operator context to use for each request.
Who can generate a Web Service Access Identifier?¶
- New operators (created after this feature became available): A Web Service Access Identifier is automatically generated when the operator is created in the system. No manual request is needed.
- Existing operators (created before this feature was available): The identifier must be requested from the EUDR support team, as it is managed by EC administrators (EC Admin, EC Support, or Technical Management roles).
How to request (existing operators only)
Contact SANTE-TRACES@ec.europa.eu with the subject line "EUDR API — Web Service Access Identifier request" and include:
- The operator name and country for which the identifier is needed
- The username of the API user that will use this identifier
- Confirmation that the user is linked to the operator in the system
Using the identifier in SOAP requests¶
Once the identifier is assigned, include it in the BodyIdentity SOAP header for every request where the API user acts on behalf of that operator:
<soapenv:Header>
<!-- WS-Security (UsernameToken) as described above -->
...
<base:WebServiceClientId xmlns:base="http://ec.europa.eu/sanco/tracesnt/base/v4">YOUR_CLIENT_ID</base:WebServiceClientId>
<body:BodyIdentity xmlns:body="http://ec.europa.eu/tracesnt/body/v3">
<OperatorAccessIdentifier>THE_GENERATED_IDENTIFIER</OperatorAccessIdentifier>
</body:BodyIdentity>
</soapenv:Header>
Behaviour summary¶
| Scenario | Behaviour |
|---|---|
User linked to one operator, no BodyIdentity header |
Works as before — operator resolved automatically |
User linked to one operator, BodyIdentity header present |
Header is used to resolve the operator |
User linked to multiple operators, BodyIdentity header present |
Header resolves the specific operator |
User linked to multiple operators, no BodyIdentity header |
Request rejected — the system cannot determine which operator to use |
Supported identifier types
Only OperatorAccessIdentifier is accepted for EUDR endpoints. Other identifier types (AuthorityActivityAccessIdentifier, OrganicControlBodyAccessIdentifier, OtherBodyAccessIdentifier) defined in the schema are not supported and will be rejected with an UnauthenticatedException.
Child element namespace
The OperatorAccessIdentifier child element must be in no namespace (unqualified). Do not apply the parent's namespace prefix to it. See the XML example above for the correct format.
Finding an existing identifier¶
If an identifier has already been assigned, it is visible in the EUDR Information System:
- Navigate to Directory → Operators → [your operator]
- Look in the "Operator Identifiers" section for an entry of type "Web Service Access Identifier"
If no identifier is present, contact the EUDR support team to have one generated.
Usage Recommendations and Limits¶
Statement (DDS / SD) Retrieval Service Limits¶
The following recommendations are intended to ensure fair and stable use of the shared EUDR Information System when accessing it via Web Services. Operators are encouraged to design their integrations so that they remain within the limits described below and avoid unnecessary load on the system.
When planning bulk retrievals, operators should design batching strategies that respect these limits and avoid repeatedly requesting the same datasets where local caching can be used instead.
Global and individual IP throttling limits¶
| Retrieval Method | Limit |
|---|---|
| Retrieved via UUID | 100 DDS / SD per call |
| Retrieved via Internal Reference Number | 1000 DDS / SD per call |
| Limit Type | Value |
|---|---|
| Global limit | 10,000 calls per minute |
| Per-IP limit | 5 calls per second |
These limits will be monitored and may be adjusted depending on system load.
Note
It is highly recommended that Web Service users respect these guidelines to allow fair use of resources for all users. Sustained abuses may lead to operator accounts being further limited.
Recommended Business Behaviour¶
To support stable and fair use of the EUDR Information System, operators and traders are encouraged to align their usage with the system's technical limits.
In addition to respecting the rate limits (10,000 requests per minute globally and 5 requests per second per IP), users should:
- Avoid unnecessary high-frequency polling — after submitting a DDS, allow at least 30 minutes before checking its status to support efficient completion of internal processes, including risk assessment.
- Use caching and structured retry intervals — this contributes to balanced system utilisation and reduces unnecessary load on the system.
- Prepare complete and accurate data before submission — this facilitates compliance with the 25 MB size limit and reduces repeated uploads.
- Consolidate DDS within the regulatory framework — rather than fragmenting them excessively, this supports efficient processing and clearer traceability.
- Organise mixing for bulk commodities in accordance with traceability rules — avoid dependence on widespread "declaration in excess" practices.
These behaviours support smooth system functioning, timely processing and checks, and fair access for all users of the public IT infrastructure.