Corporate reporting API: Changelog
What has changed on the corporate reporting API, and the rules we follow when changing it. Breaking changes are announced at least 90 days.
Last reviewed
November 2026: Allowed IP addresses and provisioning token rotation
Additive, and no action is required. Keys and tokens without allowed IP addresses keep working from anywhere, as before.
- Allowed IP addresses: an owner can lock a key or SCIM provisioning token to up to 20 public addresses or ranges. A call from anywhere else gets
403witherror_codeIP_NOT_ALLOWED, and owners are emailed - SCIM token rotation and expiry: provisioning tokens can be rotated, with the old token kept working for 24 hours or ended at once, and can be given an expiry date. See the SCIM reference
- Audit log: every change made over SCIM is recorded in your organisation’s audit log with the token prefix and the address it came from
October 2026: Key rotation and response headers
Additive, and no action is required. Existing keys and webhook endpoints keep working as before.
- Rotation: an owner can rotate a key from the API access card on your corporate settings screen. The old key either keeps working for 24 hours, so you can swap it in your systems without downtime, or stops at once if you choose
- Expiry warnings: every active owner is emailed before a key expires
- Leaked keys: a
twcorp_key found exposed in public is revoked automatically - Rate-limit headers: responses carry
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset, like the other external APIs - Version header: every response carries
API-Version, so you can log which version answered - Webhooks: an endpoint switched off after repeated failures can be reactivated, and the email saying it was switched off now goes to every active owner
October 2026: More webhook events
Additive, and no action is required. Existing endpoints keep receiving exactly the events they were subscribed to.
employee.deactivatedandemployee.reactivated: an employee’s seat was switched off or back oncontract.expiring,contract.renewed,contract.renewal_declinedandcontract.expired: your contract is nearing its end, moved later, an owner chose not to renew it, or it has endedinvoice.issuedandinvoice.paid: an invoice was issued to your organisation or paidcampaign.sent: an adoption campaign finished sending to your employees
Like the original event, each carries identifiers and timestamps only, never anything an employee put in their will.
September 2026: Initial release
The first release of the corporate reporting API, a read-only surface under /api/v1/corporate/ext/.
- Reporting:
overview/,trends/andfeature-adoption/, with small numbers hidden exactly as on your dashboard - Invoices:
invoices/, read only - Roster:
roster/, with cursor pagination andupdated_since - Authentication:
twcorp_keys sent asAuthorization: Bearertokens, with thecorporate:reporting:readandcorporate:roster:readscopes - Webhooks:
employee.activated, signed under the standard webhooks scheme - Reference: the Corporate reporting API reference, the machine-readable schema at
/api/v1/corporate/ext/schema/and the interactive console at/api/v1/corporate/ext/docs/
Rate limits
Limits are counted on a sliding window. When you go over one, the API answers 429 Too Many Requests with a Retry-After header telling you how long to wait.
Corporate reporting API
Every request to /api/v1/corporate/ext/.
- Every plan: 120 requests per minute
Counted separately for each key. Scopes: corporate:reporting:read, corporate:roster:read.
These figures come from the limits the API enforces, also served as JSON at /api/v1/portfolio/rate-limits/.
Versioning and deprecation policy
The corporate reporting API uses URL versioning: every endpoint is prefixed with /api/v1/corporate/ext/. The same rules apply to every external API, including the tools our MCP server offers AI assistants.
What counts as a breaking change
- Additive (not breaking): new fields on responses, new endpoints, new optional query parameters, new webhook events and new MCP tools. These can arrive at any time and do not change the version.
- Breaking: a removed or renamed field, endpoint or MCP tool, a changed field type, a new required parameter, or a change to how you authenticate.
Notice and support periods
- A breaking change is announced at least 90 days before it takes effect.
- When a new API version is released, the previous version keeps working at least 180 days afterwards.
- Security fixes and legal requirements may need shorter notice; we will say so here and explain why.
How you are told
- This changelog: every deprecation is listed here with its retirement date.
- Response headers: every response from a deprecated path carries
Deprecation,Sunset(the retirement date) and aLinkheader withrel="deprecation"pointing back to this page. - Machine-readable policy:
/api/v1/api-policy/returns these periods and every live deprecation as JSON.
At the retirement date
From the date in the Sunset header, the retired path answers 410 Gone with the code api_sunset and the replacement to move to. Your API key keeps working for everything that has not been retired.
Deprecation header. Together they keep an additive change from breaking you and make sure a deprecation does not go unnoticed.Staying informed
- This page: the record of every change to the corporate reporting API, worth a look once a month
- The schema:
/api/v1/corporate/ext/schema/changes with the surface, so you can diff it between releases - Webhooks: they tell you about activity in your organisation, not about API versions. Deprecation notices are never delivered by webhook
- Contact support: get in touch if you need help migrating
Note
Related topics
Can’t find what you’re looking for?
Our support team is here to help. Contact us and we’ll get back to you as soon as possible.
Contact us
