Skip to main content
Use ngrok through Corsair: one client, typed API calls. Create an API key at https://dashboard.ngrok.com/api-keys. The plugin sends it as a bearer token and also sends the 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:
  • url is the endpoint’s own address, not an upstream. Use a domain the account owns, such as the free *.ngrok-free.dev dev domain. Where requests go is decided by the Traffic Policy.
  • A cloud endpoint needs a Traffic Policy. ngrok answers 400 ERR_NGROK_18015 without one, and the policy has to end in a terminal action such as forward-internal, redirect or custom-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.create returns.
  • Reserving a domain needs a paid plan (free accounts get ERR_NGROK_401; they have one dev domain with is_dev: true and a null cname_target).
  • Reserving a domain does not make it serve traffic. domains.create returns a cname_target; point DNS at it, and certificate issuance starts once the record resolves. certificate_management_status.provisioning_job reports how that went.
  • An API key’s token is returned once. apiKeys.create includes the token in its response and never again; a later apiKeys.list or 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 the before_id value in its query, as before_id; the plugin sends only the id. Keep the same limit and filter.
  • Event subscriptions need destinations that already exist. events.create takes destination_ids, and destinations are created through a separate ngrok API that this plugin does not wrap.
Errors carry a globally unique code, and two of them share a 403: 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
With multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.
3

Choose authentication

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 endpoints
Reserve a custom domain
See the full list on the API page.

What’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.