IRIS A2A developer guide: Client ID, JWT tokens, endpoints, UTIDs and ATS testing

The four registrations, in order

Each step depends on the one before it: the Client ID application asks for the TCC, consent needs the Client ID, and the token request needs the UserID that consent produces. A TCC from FIRE, AIR, MeF or the IRIS Taxpayer Portal does not work on A2A; Publication 5718 lists all five as separate (section 1.3). The Taxpayer Portal and A2A are different TCC applications, so a firm that uses both holds two IRIS TCCs.

1. The IRIS A2A TCC and its roles

The application offers three roles, and they decide which TCC you transmit with and what testing you owe (Pub 5718 1.3.2, Table 1-1):

Roles combine. A vendor is Software Developer plus Transmitter and gets two TCCs; a company that built its own software is Software Developer plus Issuer. A developer who is also a transmitter does not repeat the communication test. What the application needs: the firm's EIN (never an SSN or ITIN), legal and DBA names, a physical business address, and for each Responsible Official, Contact and Authorized Delegate an SSN or ITIN, date of birth and contact details; every RO signs with a five-digit PIN (Pub 5718 1.3.4). The Application Summary page usually shows within 48 hours, the TCC letter by mail within 45 days. A TCC unused for three consecutive years is deleted and cannot be revived. The TCC lifecycle guide covers the application screens and what happens to a FIRE TCC.

2. API Client ID and the JWK

With the TCC in hand you file a second application, the API Client ID Application, from the "Get an API Client ID" link on IRS.gov/iris. It is the same e-Services application used for other IRS APIs: sign in, choose Individual on the Select Your Organization page, New Application, API Client ID Application; if you already hold one for another API, edit it and tick the IRIS box instead (an existing Client ID that is only for IVES Forms Based Processing does not qualify, and you create a new one). The Client ID is issued at the end of the application, and the Responsible Official or Contact reads it off the Application Details or Summary page (Pub 5718 1.6).

The application will not complete without a JSON Web Key. Publication 5718 is specific about it:

• An RSA public key, represented as a JWK, backed by an X.509 certificate from a public certificate authority. Self-signed certificates are refused. The certificate already used for MeF or AIR can be reused.
• Exactly seven attributes, in this order, with everything else removed: kty (RSA), kid, use (sig), n, e (AQAB), x5c (the certificate chain) and x5t (the SHA-1 thumbprint). A missing attribute makes the JWK invalid; the publication says to paste the full object, braces included, and suggests a text editor for reordering.
• The JWK expires when the certificate does, and it is on you to track that date and upload a replacement. The checker below reads the dates out of the certificate.

The kid matters later: every JWT you sign must carry the same kid in its header, case sensitive, or the token request fails (Pub 5718 3.1.2).

3. Consent in the IRS Consent App

A Client ID cannot act for an e-Services user until that user has said so. The transmitter signs in to the IRS Consent App, chooses the organization tied to the IRIS TCC application (not the API application), selects Setup on API Authorization Management, enters the IRIS Client ID, and grants access to TEST and to PROD. The A2A Setup Complete page then shows the full IRIS UserID, in the form dasmith-345870: the e-Services username, a hyphen and a number. Write it down; it is the sub of the User JWT and nothing else on the token request identifies the user (Pub 5718 3.1.1).

4. Access tokens: two JWTs

IRIS uses the OAuth JWT bearer flow of RFC 7523. Every token request carries two JWTs, both signed RS256 with the private key behind the JWK: a Client JWT that authenticates the software, and a User JWT that names the user the software is acting for. The IRS verifies both signatures against the JWK on the Client ID application, then checks that the user in the User JWT has consented to the client in the Client JWT (Pub 5718 3.1.2).

The request is a form POST to https://api.www4.irs.gov/auth/oauth/v2/token (production) or https://api.alt.www4.irs.gov/auth/oauth/v2/token (ATS) with four fields: grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, assertion holding the User JWT, client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer, and client_assertion holding the Client JWT. A 200 returns access_token, token_type Bearer, refresh_token and expires_in 900. Access tokens live 15 minutes and refresh tokens 60; a token only has to be valid when a transmission starts, so a large upload that runs past 15 minutes is not cut off (Pub 5718 3.1.2 notes).

The two endpoints

The publication's own example is a one-line curl: curl -i -X POST -H "Content-type: multipart/form-data" -H "Authorization: Bearer <token>" -F "file=@1099MISC.xml; type=text/xml" https://<host>/irisa2a/v1/intake-acceptance. A successful post returns three things to keep with the file: the Receipt ID, the UTID and a timestamp. New for tax year 2025, a status request by UTID returns the Receipt ID in the response, so a Receipt ID lost to a timed-out session no longer needs a Help Desk call (Pub 5718 3.1).

UTID, Receipt ID and the pipe-separated IDs

Every transmission carries a Unique Transmission Identifier in the manifest: da20a4de-1357-11ed-861d-0242ac120002:IRIS:D1234::A, meaning a UUID, the literal IRIS, your TCC, an empty reserved field and A for A2A. IRIS rejects a UTID it has seen before, including on a transmission that was rejected, and the TCC inside it must equal the TransmitterControlCd element (Pub 5718 2.2; Pub 5719 4.2). Inside the transmission each submission has a Submission ID and each record a Record ID; IRIS answers with a Receipt ID. Those three are the handles for everything that follows:

• OriginalUniqueSubmissionId = RECEIPTID|SID goes in the submission header of a replacement for a rejected submission (TransmissionTypeCd R).
• UniqueRecordId = RECEIPTID|SID|RID goes in a corrected record (TransmissionTypeCd C) for a record that was accepted or accepted with errors.

A transmission holds one type only, O, C or R, never mixed; each submission holds one form type and one tax year; and the record count in the submission header must equal the records inside (Pub 5718 2.1). The corrections guide has the full correction and replacement sequences, and the error code pages cover the rules that fire when they are wrong.

ATS: what a passing test looks like

The Assurance Testing System is open all year. Test transmissions set the Test File Indicator to T, use the Software Developer TCC (developers) or the Transmitter TCC (communication tests), carry a Software ID the IRS can verify, and use the transmitter name and EIN exactly as on the TCC application. Every issuer and recipient TIN in a test file begins with three zeros (000-11-1111, 00-0111111); live data in ATS is rejected and the environment is not treated as secure. The transmitter block is the exception: it uses the real EIN (Pub 5719 4.2, 6.1.1).

In ATS, Accepted with Errors and Rejected are both answered by fixing the file and resending it as a new original (new UTID) until Accepted comes back; the correction and replacement transmission types are for production (Pub 5719 Table 4-1). Processing that sits longer than seven days is a Help Desk call. The schema package and sample transmissions come from the Secure Object Repository, which opens to TCCs with the Software Developer role or a government business structure.

Tools: JWT claims, UTID and record IDs, JWK check

JWT claims builder

Builds the header and both payloads for a token request with the timing rules applied. It does not sign anything; sign each payload in your own code with the private key that matches the kid.

UTID and record ID builder

A fresh UTID for a transmission, and the pipe-joined identifiers a correction or replacement must quote.

JWK checker

Checks the public key object against the seven attributes the application accepts, flags extras and ordering, and reads the validity dates out of the certificate.

What goes wrong

• Wrong TCC. A FIRE or Taxpayer Portal TCC in the manifest, or a Software Developer TCC on a production file. The UTID's TCC and the manifest's TransmitterControlCd must match and must be the A2A TCC for that role.
• JWK rejected by the application. An extra attribute (alg, x5u, key_ops), the attributes out of order, a self-signed certificate, or a JWKS wrapper when the field wants one key object.
• Token request fails. kid mismatch or case; iat or exp with a decimal; exp more than 15 minutes out; the User JWT's sub holding the e-Services username without the numeric suffix; consent granted to a different Client ID than the one signing.
• Token valid in ATS, refused in production. Consent was granted to TEST only; PROD is a separate grant in the consent app.
• Transmission rejected before processing. Reused UTID, including the UTID of the transmission being replaced; payload sent as a body instead of a file part; a file over 100 MB; mixed transmission types or tax years in one file.
• Acknowledgment looks lost. Query by UTID; since tax year 2025 the response carries the Receipt ID.
• Lapsed credentials. The JWK expired with its certificate, or the TCC was deleted after three years without a transmission.

Questions people ask