> For the complete documentation index, see [llms.txt](https://irisfile.co/llms.txt). Markdown versions of every page are available by appending .md to its URL (the home page is /index.md). # Set up API keys and webhooks Choose a live or sandbox API key for your IRISfile integration, and add a webhook endpoint for filing events. Revoke the key when you stop using it. [All help articles](https://irisfile.co/help)Last reviewed October 2026 Click API keys in the dashboard top bar, type a name and choose Live or Sandbox. Live is the default and works with the MCP server at https://irisfile.co/mcp. Sandbox keys are for the IRISfile API private beta and never file a live return. Click Create key, then Copy: IRISfile shows the key only once. To stop it working, click Revoke, then Confirm revoke. For filing events, click Add endpoint under Webhooks and copy the signing secret: it also shows once. Key facts **Where**: API keys in the dashboard top bar **Shown**: Once, when you create the key **Active keys**: Up to 10 per account **Reach**: Every file in your account **Kinds**: Live (irf\_live\_, the default) or Sandbox (irf\_test\_) **Endpoint**: https://irisfile.co/mcp, live keys only **Webhooks**: Up to 5 endpoints per environment, secret shown once ## Before you start **Account**: An IRISfile account you can sign in to. **Client**: Claude, Cursor or another MCP client, or your own code that calls the IRISfile API. **Webhook URL**: An https URL on the default port whose host is a public host name or a public IP address. ## Step by step 1. ### Open API keys and create a key Sign in and click API keys in the top bar. The page says what a key can reach and lists your keys. Type a name in Key name, such as the client the key is for. Choose Live for MCP or Sandbox for the API private beta, then click Create key. A name can be up to 60 characters. [![The API keys page with the Key name field, Key kind selector and Create key button.](https://irisfile.co/images/help/create-an-api-key/01-form-d63185fd.webp)](https://irisfile.co/images/help/create-an-api-key/01-form-d63185fd.webp) The API keys page with a key name typed and Create key outlined. [Open full size](https://irisfile.co/images/help/create-an-api-key/01-form-d63185fd.webp) 2. ### Copy the key IRISfile shows the new key under the form. Click Copy, then paste the key into your AI client. IRISfile stores only a fingerprint of the key, so it can't show the key again. Click Done when you have it. If you lose a key, create a new one and revoke the old one. [![The new key under the form, with its middle hidden for this screenshot, and the Copy button outlined beside the Done button.](https://irisfile.co/images/help/create-an-api-key/02-created-087d4d5d.webp)](https://irisfile.co/images/help/create-an-api-key/02-created-087d4d5d.webp) The new key, shown once, with Copy outlined. Its middle is hidden for this screenshot. [Open full size](https://irisfile.co/images/help/create-an-api-key/02-created-087d4d5d.webp) 3. ### Add the key to your client The client sends the key with every call, as an Authorization: Bearer header or an x-api-key header. An AI client calls https://irisfile.co/mcp with a live key. In Claude Code, run claude mcp add with the endpoint and the header. In Claude or Cursor, add the endpoint and the header in the client's connector settings. The IRISfile MCP server page has the exact setup for each client. Your own code calls the API at https://irisfile.co/api/v1 with a sandbox key. The API docs have a quick start that files two test records with the IRS sandbox. 4. ### Check when a key was last used Your keys table lists each key's name, the first characters of the key, its kind, the date it was created and the date it was last used. A key that has never connected reads Never. Use Last used to find a key that nothing uses any more, then revoke it. [![The Your keys table with one active key: its name, prefix, kind, dates and Revoke button.](https://irisfile.co/images/help/create-an-api-key/03-row-30649397.webp)](https://irisfile.co/images/help/create-an-api-key/03-row-30649397.webp) The new key under Your keys: Active, never used, with Revoke outlined. [Open full size](https://irisfile.co/images/help/create-an-api-key/03-row-30649397.webp) 5. ### Revoke a key Click Revoke on the key's row. The button changes to Confirm revoke for 4 seconds; click it again to revoke the key. The key's status changes to Revoked with the date. The key fails on its next call, and the row stays in the list as a record. [![The same key's row after revoking it: the status reads Revoked with the date, and the Revoke button is gone.](https://irisfile.co/images/help/create-an-api-key/04-revoked-7b3beadb.webp)](https://irisfile.co/images/help/create-an-api-key/04-revoked-7b3beadb.webp) After Confirm revoke the key reads Revoked with the date, and its Revoke button is gone. [Open full size](https://irisfile.co/images/help/create-an-api-key/04-revoked-7b3beadb.webp) 6. ### Add a webhook endpoint and copy its secret Under Webhooks on the same page, type your https URL in Endpoint URL. In Files, choose Sandbox for events about sandbox files or Live for live files, then click Add endpoint. IRISfile shows the endpoint's signing secret once. It starts with whsec\_. Click Copy, store the secret with your server's other secrets, then click Done. If you lose it, delete the endpoint and add it again. [![The Webhooks panel after Add endpoint: the cleared form, and under it the new signing secret for https://example.com/irisfile/webhook, its middle hidden, with Copy outlined.](https://irisfile.co/images/help/create-an-api-key/05-webhook-secret-2a519bad.webp)](https://irisfile.co/images/help/create-an-api-key/05-webhook-secret-2a519bad.webp) The new endpoint's signing secret, shown once, with Copy outlined. Its middle is hidden for this screenshot. [Open full size](https://irisfile.co/images/help/create-an-api-key/05-webhook-secret-2a519bad.webp) 7. ### Send a test event and check the signature Click Send test on the endpoint's row, and the button reads Test sent. IRISfile posts a webhook.test event to the URL. Reload the page to see the result under Last delivery: Delivered with the date, Retrying, or Failed after 7 tries. Each post carries an IRISfile-Signature header: t=,v1=. Your server computes an HMAC-SHA256 of the timestamp, a period and the raw body, keyed with the secret, and compares it with v1. Reject a post whose timestamp is more than 300 seconds from your server's clock. The API docs have a Node.js function that does this check. After the test event works, the endpoint gets an event when a file finishes converting, when the IRS gives a transmission its receipt or acknowledgement, and when a transmission fails. [![The endpoint's row under Webhooks: the URL, Sandbox, the last 4 characters of the secret, No deliveries yet, and the Send test button outlined.](https://irisfile.co/images/help/create-an-api-key/06-webhook-row-c1df07d4.webp)](https://irisfile.co/images/help/create-an-api-key/06-webhook-row-c1df07d4.webp) The endpoint under Webhooks: its URL, Sandbox, the secret's last 4 characters, and Send test outlined. [Open full size](https://irisfile.co/images/help/create-an-api-key/06-webhook-row-c1df07d4.webp) ## If something goes wrong **The API key has been revoked.**: The client is still sending a key you revoked. Create a new key and replace the old one in the client's settings. **The API key is not valid.**: The client is sending an invalid key, or a sandbox key to the MCP server. Copy a live key again: it starts with irf\_live\_. Sandbox keys start with irf\_test\_. Check that nothing else is in the header. **An account can hold 10 active keys. Revoke one first.**: Your account already has 10 active keys. Revoke a key you no longer use, then create the new one. **Rate limit reached: 60 requests per minute per API key.**: The key made more than 60 calls in one minute. Wait for the time in the message, then try again. **The URL's host resolves to a private or reserved address.**: IRISfile posts only to public addresses. Use the public https URL of your server, not localhost, a private IP or an internal host name. **An account can hold 5 endpoints per environment. Delete one first.**: The Sandbox or Live list already has 5 endpoints. Click Delete on one you no longer use, then Confirm delete, and add the new one. ## Questions **Can I see a key again after I click Done?**: No. IRISfile keeps only a fingerprint of each key, so nobody can read it back. Create a new key, then revoke the one you lost. **What can an agent do with my key?**: Through the MCP server, it can list supported forms, check and convert files, and read the status of every file in your account. The MCP tools can't file with the IRS or pay for forms. The same key also works with the IRISfile API: there it can upload and convert files, debit form credits and file transmissions. A live key files with the IRS. A sandbox key files with the IRS test system. Treat a key like a password, and give it only to code and clients you trust. **Does a key cost anything?**: No. Creating a key and calling the MCP tools are free. Through the API, converting and validating are free. Downloading XML needs a license for the file's tax year and debits nothing. A Portal CSV download and a filing with the IRS debit form credits for forms you have not paid for. A qualifying sandbox file needs no license and no credits. **How many keys can I have?**: Up to 10 active keys per account. Revoked keys don't count toward the limit, and they stay in the list. **Why does my webhook endpoint fail when the URL works?**: IRISfile counts only a 2xx answer within 10 seconds as delivered, and a redirect counts as a failure. Answer the post directly with 200 or 204, and check the signature before you act on the event. ## Related - [Upload and convert a 1099 file](https://irisfile.co/help/upload-and-convert) - [Fix validation errors](https://irisfile.co/help/fix-validation-errors) - [IRISfile MCP server](https://irisfile.co/mcp-server) - [IRISfile API docs](https://irisfile.co/docs/api) [Check a FIRE file for free](https://irisfile.co/tools/fire-validator) or [See pricing](https://irisfile.co/pricing) Try it on a file you already have. [Get notified](https://irisfile.co/sign-up)