Every few months someone asks us the same question: can we authenticate users with the Portuguese Citizen Card inside our own application? The answer is yes, and the path is more open than most teams expect. The official middleware is published as open source by AMA, covering the Cartão de Cidadão, Chave Móvel Digital and the professional attribute certification system.
What catches teams out is not the cryptography. It is the reader layer, the choice between authentication and qualified signature, the certificate chain, and what happens when the card in front of you is a version your code has never seen.
The relevant date is June 2024. That is when Portugal began issuing the Cartão de Cidadão v2, redesigned for the security and format standards of Regulation (EU) 2019/1157, which had been in application since 2 August 2021 and was replaced by Regulation (EU) 2025/1208 on 9 July 2025. The v2 card uses ECDSA keys where v1 used RSA, and it supports contactless reading. Version 3.12.0 of the middleware was the first to support it. If your integration predates mid-2024 and nobody has touched it since, it is running against assumptions the card no longer satisfies.
Is the middleware open to private applications, or only to the state?
Open to anyone. The source, the SDK and the technical documentation are all public. There is no licensing negotiation and no approval gate for reading identity attributes or performing an authentication.
What is gated is different. Issuing credentials is a state function. Acting as a qualified trust service provider requires supervision, and Autenticação.gov is the state service behind it. Using professional attributes involves the authorities that issue them. Reading the card and verifying a signature does not.
What is the difference between authentication and qualified signature?
The card carries two separate certificates with two separate PINs and two very different legal effects. Choosing the wrong one is the most expensive mistake available at the start of a project, because it changes your architecture, your retention obligations and your scope.
For completeness: the card has three PINs, authentication, signature and address, plus a longer cancellation code used to disable the digital functions if the card is lost or stolen. All of them arrive in the PIN letter sent to the citizen.
Why does the card reader break more projects than the cryptography?
Because the cryptography is standardised and the reader layer is not. A browser cannot talk to a smart card on its own. The middleware has to be installed on the user machine, and everything about that is outside your control.
Contactless changes this, partly. The v2 card supports contactless reading, which removes the reader from the equation for mobile scenarios. It introduces the CAN, a six-digit number printed on the card, required for contactless operations and distinct from the three PINs. When calling C_Login through PKCS#11 in contactless mode with a v2 card, the CAN is passed as the PIN parameter.
What changes between Cartão de Cidadão v1 and v2 for your code?
Enough that code written only against v1 will not behave correctly against v2. And the middleware provides no direct way to ask which version is in the reader.
What does each scope actually add to the build?
The variable that drives effort is not the cryptography, which is fixed. It is how many of the following you need, and each one brings its own dependencies and failure modes.
We are not publishing price ranges here, because the honest answer depends on which of these apply, how many platforms you support and what your audit requirements are. Send us the scope and we will give you a number rather than a range.
What do you have to keep, and for how long?
For authentication, you are proving that a verification took place: the fact of it, when, which certificate, and the result of the chain and revocation checks. Not a copy of everything on the card. Under data minimisation, storing the full identity dataset because it was available is a liability rather than a record.
For qualified signature, you are proving something harder: that the signature was valid at the moment it was made, verifiable years later, after the certificate has expired. That requires the signed document, a trusted timestamp, and the validation material captured at signing time.
Two decisions to make explicitly. Do you store the citizen number or a derived identifier, since a pseudonymous internal identifier covers most use cases and reduces exposure considerably. And do you re-verify on every session or trust a session token after the first check, an answer that depends on the risk of the operation and should be written down rather than inherited from whatever the developer chose.
How does this relate to the EUDI Wallet arriving in December 2026?
Every EU member state must make a European Digital Identity Wallet available by 24 December 2026, with obligated private-sector organisations required to accept it roughly a year later. That does not make the Citizen Card obsolete, and the two are not alternatives in the short term. The practical position for the next two to three years is that both will be presented.
Which argues for one architectural decision now. Keep your verification logic behind an interface that does not know which mechanism produced the result. If your application code asks whether this person was verified and to what level, rather than what the card returned, adding wallet acceptance later is an implementation and not a rewrite. Our guides on eIDAS 2.0 implementation and relying party integration cover that side.
Related reading
Frequently asked questions
Access and licensing
Is the Portuguese Citizen Card middleware free to use commercially?
Can a web application read the Citizen Card directly?
The new card
What is the CAN and when do you need it?
Will code written for the old Citizen Card work with the new one?
Deployment and what comes next
What has to be installed on the user device?
Does the EUDI Wallet replace the Citizen Card?
