Ngrok-Version: 2 header every request needs; without that header the API answers a version error that reads like an auth failure.
Things worth knowing:
urlis the endpoint’s own address, not an upstream. Use a domain the account owns, such as the free*.ngrok-free.devdev domain. Where requests go is decided by the Traffic Policy.- A cloud endpoint needs a Traffic Policy. ngrok answers 400
ERR_NGROK_18015without one, and the policy has to end in a terminal action such asforward-internal,redirectorcustom-response. It is text (YAML or JSON), not an object. - Creating an endpoint makes it live. It serves on its URL as soon as
endpoints.createreturns. - Reserving a domain needs a paid plan (free accounts get
ERR_NGROK_401; they have one dev domain withis_dev: trueand a nullcname_target). - Reserving a domain does not make it serve traffic.
domains.createreturns acname_target; point DNS at it, and certificate issuance starts once the record resolves.certificate_management_status.provisioning_jobreports how that went. - An API key’s token is returned once.
apiKeys.createincludes thetokenin its response and never again; a laterapiKeys.listor read omits it. Store it when it is minted, because there is no way to read it back. - Paging is by id, not page number. A list answers
next_page_uri, the full URL of the next page, or null on the last page. Pass that URL, or thebefore_idvalue in its query, asbefore_id; the plugin sends only the id. Keep the samelimitandfilter. - Event subscriptions need destinations that already exist.
events.createtakesdestination_ids, and destinations are created through a separate ngrok API that this plugin does not wrap.
ERR_NGROK_200 means no Authorization header was sent, while ERR_NGROK_202 means the credential does not look like a key. The plugin reports both as auth failures, and keeps the operation_id that ngrok support asks for. A 5xx on a read is retried; a 5xx on a create, update or delete is not, because it may have gone through.
What you get:
- 18 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the ngrok API key before the first call: More: API Key
pnpm corsair setup --plugin=ngrok --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
List the first endpointsWhat’s next
API reference
Every
ngrok.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.