Free IRIS developer guide
Getting an IRIS API Client ID
IRIS A2A software authenticates with an API Client ID, a registered public key and signed JWTs. Here's the application step by step, what the JSON Web Key must look like, the consent step people miss, and how tokens work. Plus a checker that catches JWK problems before the IRS does.
Runs entirely in your browser and only uses public keys. Nothing is sent to us or stored.
Short answer
An IRIS API Client ID identifies your A2A software to the IRS. You apply after getting an IRIS A2A TCC, through the API Client ID Application in e-Services, and register a JSON Web Key: your RSA public key with an X.509 certificate that isn't self-signed (the MeF or AIR certificate can be reused). Then grant the Client ID access to TEST and PROD in the IRS Consent App. Your software signs a Client JWT and a User JWT with RS256 and exchanges them for an access token valid for 15 minutes; refresh tokens last 60 minutes.
- The JWK expires when its certificate does
- JWT iat and exp: whole-second epoch times, 15 minutes apart
- Each JWT needs a unique jti
- The User JWT subject is your IRIS UserID, like dasmith-345870
Last reviewed against IRS Publication 5718 and the IRS Get an API Client ID page.
JWK checker Paste your public JWK (or JWKS) to check and format it for the application.
Public key only. If you paste something containing a private key ("d", "p", "q"…), the checker stops and won't display it.
JWT claims builder The header and payloads your software signs for the token request.
The timestamps are a 15-minute window starting now. Signing happens in your own software with your private key; this page never needs it.
Before you apply
- An IRIS A2A TCC. You apply for the Client ID after the TCC. See the IRIS TCC guide.
- An IRS e-Services account verified with ID.me (photo ID ready).
- An X.509 digital certificate that isn't self-signed. The one you use for MeF or AIR is fine.
- Your RSA public key as a JWK with that certificate attached (below). Keep the private key in your own systems.
The application and setup, step by step
- Open Get an API Client ID. From irs.gov/iris, choose Get an API Client ID under the A2A steps, then Sign in or create an account (have photo ID ready for identity verification). IRS: Get an API Client ID
- Select Individual. On Select Your Organization, choose Individual, and keep choosing it until the application is complete. If you already have a Client ID application, open it instead.
- Start or edit the application. New: choose New Application, then API Client ID Application. Existing: open it under All Applications, select the edit icon, tick IRIS under Select APIs and resubmit. An application that's only for IVES Forms Based Processing needs a new Client ID.
- Add your JWK. Paste your JSON Web Key: an RSA public key with its X.509 certificate (not self-signed), attributes in the IRS order. The certificate is validated during the application.
- Submit and get the Client ID. With no errors you'll see Submission Complete. The Client ID appears on the Application Details or Application Summary page, where the Responsible Official or a Contact can retrieve it.
- Grant consent. In the IRS Consent App, select the organization on your IRIS TCC application (not the API application), choose Setup, enter your IRIS Client ID, and grant access to TEST and PROD. Note the full IRIS UserID it shows.
- Request access tokens. Your software signs a Client JWT and a User JWT with your private key (RS256) and exchanges them at the token endpoint for an access token. Token details: Publication 5718
You can save the application partway through and come back later.
What the JWK must contain
| Order | Attribute | Value |
|---|---|---|
| 1 | kty | Key type: must be RSA |
| 2 | kid | Key ID: your JWTs must use it exactly (case sensitive) |
| 3 | use | Public key use: sig |
| 4 | n | The RSA modulus |
| 5 | e | The public exponent: AQAB |
| 6 | x5c | X.509 certificate chain |
| 7 | x5t | X.509 certificate SHA-1 thumbprint |
- Keep the order above and remove every other attribute (key tools often add alg or key_ops).
- Paste the whole object, braces included. A missing attribute makes the JWK invalid.
- The JWK expires when the certificate does. Track the date (open the certificate file to see its end date) and submit a new JWK before then.
Consent: the step people miss
The Client ID alone doesn't let your software act for you. In the IRS Consent App:
- Sign in and, on Select Your Organization, pick the organization on your IRIS TCC application, not your API application.
- Choose Setup on the API Authorization Management page and enter your IRIS Client ID (if you have several, the one issued for IRIS).
- Grant access to TEST (for ATS) and PROD (for live filing).
- Copy your full IRIS UserID from the A2A Setup Complete page (format like dasmith-345870). It goes in your User JWT.
How the tokens work
- Your software signs two JWTs with your private key using RS256, each with alg and kid in the header:
- Client JWT: iss and sub = your Client ID.
- User JWT: iss = your Client ID, sub = your IRIS UserID.
- Both: aud = the token endpoint, exp 15 minutes after iat (whole-second epoch times, no decimals), and a unique jti.
- POST them (form-encoded) to the token endpoint with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, the User JWT as assertion, and the Client JWT as client_assertion with client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
- Token endpoints: production https://api.www4.irs.gov/auth/oauth/v2/token; ATS https://api.alt.www4.irs.gov/auth/oauth/v2/token.
- You get an access token valid for 15 minutes and a refresh token valid for 60. The access token only needs to be live when a transmission starts, and you can reuse it until it expires.
The assertion/client_assertion split follows the OAuth JWT profile (RFC 7523) that Pub 5718 references. What to send once you have a token is in the IRIS A2A developer guide, and testing is covered in the ATS testing guide.
Sources
Questions
IRIS API Client ID questions
What is an IRIS API Client ID?
The credential that lets your software talk to IRIS A2A. IRS e-Services uses it, with the public key you register, to authenticate your application and authorize it to send information returns and fetch acknowledgments. You apply for it after you have an IRIS A2A TCC.
Can I use a self-signed certificate for my IRIS JWK?
No. The JWK must include an X.509 certificate chain (x5c) and thumbprint (x5t), and the IRS doesn't accept self-signed certificates. You can reuse the certificate you use for other IRS programs such as MeF or AIR.
What attributes does the IRIS JWK need?
Exactly seven, in this order: kty (RSA), kid, use (sig), n, e (AQAB), x5c and x5t. Remove any others, and paste the whole object including the curly braces. If one is missing, the JWK is invalid.
What happens when my certificate expires?
Your JWK expires with it. You're responsible for tracking the date and providing a new JWK on your API Client ID application before then.
Why do I get an error requesting an access token?
Common causes: the JWT header's kid doesn't exactly match the kid in your registered JWK (it's case sensitive); the algorithm isn't RS256; exp isn't 15 minutes after iat, or the times have decimals; jti is missing; the User JWT doesn't use your full IRIS UserID; or consent hasn't been granted for that environment.
Is my key sent anywhere when I use the checker?
No. The checker runs in your browser and only needs your public key. It refuses private keys, and nothing is uploaded or stored.
Do I need an API Client ID to e-file 1099s?
Only to build or run your own A2A integration. The IRIS Taxpayer Portal doesn't use one, and if an authorized e-file provider files for you, you don't need a TCC or Client ID at all.
File without the integration work
EFileForMe is an authorized e-file provider. Create a free account, enter or import your forms, and we file them with the IRS. No TCC of your own, no certificates, no API keys.