Authenticate with AEAT

Use this guide before a command needs read-only live access to AEAT, such as pulling Modelo 036 census information.

Authentication is local setup for read access. It does not let aeat submit filings, register Modelo 036 changes, or modify AEAT records.

Before you start

You need:

  • an active profile — aeat config auth configure refuses with No hay un perfil activo until you create one. Create one non-interactively with aeat config profile create me --quiet --tax-id <NIF/CIF/DNI/NIE> --name "Ana" --surnames "Garcia Lopez".

  • the master-key passphrase that protects your local store. The tool prompts for it, or set AEAT_SECRET_PASSPHRASE to run without a prompt.

See supported providers

List providers:

aeat config auth providers

The list marks each provider as disponible (available now) or reservado (no disponible aún) (reserved, not available yet). Three are available:

  • certificate — your digital certificate file (certificado digital). Available.

  • clave_movil — mobile-based Cl@ve, confirmed on your phone. Available.

  • clave_permanente — Cl@ve Permanente, a DNI/NIE and password login. Available.

Two more are listed but reserved, so you cannot configure them yet:

  • clave_pin — Cl@ve PIN (a one-time code system from AEAT). Reserved.

  • dnie_pkcs — the national ID card (DNI electrónico). Reserved.

Configure one of the available providers.

Configure a provider

Configure the provider you use:

aeat config auth configure --provider certificate --file ./certificate.p12

Use --file for providers that need a file, such as your digital certificate. Keep credential files private and do not share them.

Check local readiness

Check what is configured:

aeat config auth status
aeat config auth test

Use --provider with either command when you want to inspect a specific provider.

Renew your certificate before it expires

A digital certificate has an expiry date. The tool reads that date from the certificate file and warns you as it approaches, so a live read never fails because the certificate lapsed unnoticed.

Check the remaining validity:

aeat config auth test

The report tells you how the certificate stands:

  • More than 60 days left: the certificate is valid and reports the days remaining.

  • 60 days or fewer left: a warning appears — The certificate expires in N days. Plan the renewal. Start the renewal now.

  • 14 days or fewer left: the warning is critical. Renew before your next live read.

  • Already expired: The certificate expired N days ago. Renew it before authenticating. A live read is refused until you replace it.

Renew the certificate with the body that issued it — for example the FNMT (Fábrica Nacional de Moneda y Timbre) or AEAT. This happens outside the tool. Download the renewed certificate file (.p12 or .pfx) to your machine.

Point the tool at the renewed file:

aeat config auth configure --provider certificate --file ./renewed-certificate.p12

If the renewed certificate uses a new password, update the AEAT_CERTIFICATE_PASSWORD_SECRET environment variable before you re-check.

Confirm the new expiry:

aeat config auth test

The report now shows the renewed certificate’s later expiry date.

Manage several certificates

If you act for several entities (for example a gestor managing several taxpayers), register one certificate per entity instead of reconfiguring auth configure --file every time you switch.

Register each certificate under a name:

aeat config auth certificate register --name personal --file ./personal.p12
aeat config auth certificate register --name apoderado-acme --file ./acme.p12 --friendly-name "ACME SL"

List every registered source:

aeat config auth certificate list

Select the one you want active:

aeat config auth certificate select --name apoderado-acme

Remove a source you no longer need:

aeat config auth certificate remove --name personal

Check every certificate’s expiry

Each registered certificate has its own expiry date. Check all of them in one pass, not only the active one:

aeat config auth certificate check

The report lists each source with its status:

  • ok — valid, with the days remaining.

  • expiring — within the renewal window (60 days or fewer by default, or 14 days or fewer for the critical window). A warning names the source.

  • expired — already expired. A warning names the source.

Renew an expiring or expired certificate with the body that issued it, then re-register it under its existing name:

aeat config auth certificate register --name apoderado-acme --file ./renewed-acme.p12

Re-run aeat config auth certificate check to confirm the new expiry date.

Acquire or verify a live session

When you are ready to use a live-read command:

aeat config auth login

Force a fresh authentication when needed:

aeat config auth login --fresh

Use --reset-lock only when a previous login was interrupted and left the authentication step stuck. Run it if login reports that another login is already in progress when it is not.

Clear local auth metadata

Clear one provider:

aeat config auth clear --provider certificate

Clear sessions or locks:

aeat config auth clear --sessions
aeat config auth clear --locks

Clear all configured providers only when you intend to reset authentication setup:

aeat config auth clear --all

Act for someone else (apoderado)

If you act as an authorized tax representative for another taxpayer (a gestor, asesor, or authorized agent), record locally who you represent and under which AEAT apoderamiento scopes.

The apoderamiento itself is granted at AEAT: the represented party authorizes you through AEAT’s own apoderamiento procedures. The commands below only record that grant in your local profile so live-read commands know whose data they read. They never register, extend, revoke, or renounce an apoderamiento at AEAT — there is no command that writes representation state to AEAT.

See the accepted scopes

List the scope codes the tool accepts:

aeat config auth apoderado scopes list

Each scope is an AEAT apoderamiento area, and some bind specific modelos — for example RENT (modelos 100, 714), IVA (303, 390), PAGOSF (130, 131), RETEN (withholding modelos), plus GENERALNT, CENSO, INFORM, NOTIFIC, and EXPED.

Record who you represent

Set the represented party’s tax identifier (NIF, CIF, DNI, NIE, or NII) and the scopes that match the grant at AEAT:

aeat config auth apoderado configure --represented-nif <nif> --scope IVA --scope PAGOSF

Repeat --scope for each code — a comma-separated list is rejected. Scope codes are uppercase. Use --scope ALL to record every catalogue scope at once. Unknown codes are refused with the accepted set named.

The active profile holds at most one apoderado configuration; configuring again replaces it. The represented identifier is stored encrypted.

Review or retire the configuration

Show what is recorded for the active profile:

aeat config auth apoderado status

aeat config auth apoderado check is the live-verification verb, but the live AEAT-read path is sealed, so it refuses with a “live verification unavailable” message and points you back to status. Use aeat config auth apoderado status for the offline configuration read.

Remove the configuration when the representation ends:

aeat config auth apoderado clear

Clearing removes only the local record. The apoderamiento at AEAT is unaffected — revoke it through AEAT’s own procedures.

Next steps

Run aeat config auth test from time to time to catch an expiring certificate early, and follow Renew your certificate before it expires when the warning appears.