Using Insomnia?

Insomnia sync broken or auth flow stuck? We clear the backlog.

Insomnia is a solid Postman alternative once it is set up for how your team actually works. Sync plugin trouble, OAuth that refreshes to a dead token, environments that leak production values into staging. We tidy the workspace, split the environments properly, and leave you with a tool your engineers trust during an incident.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

insomnia-sync.log

stuck

What it is

Insomnia at a glance

Insomnia is an open-core API client originally released in 2016 by Gregory Schier and acquired by Kong in 2019. It handles REST, GraphQL, gRPC, WebSockets and server-sent events, with environments, cookies, request templating and a plugin system. It is used by teams who want a cleaner, more keyboard-driven alternative to Postman without giving up collaboration.

The free Scratch Pad tier works offline. Paid tiers add Kong Cloud or Git-based sync, collaboration, and enterprise features like SSO and Insomnia for Teams. Insomnia also doubles as a design tool for OpenAPI with linting via Spectral and inspection against a running service.

Type
API client and design tool
First released
2016
License
Apache 2.0 open source core, proprietary cloud features
Maintained by
Kong, Inc.
Typically used for
Testing REST, GraphQL and gRPC APIs, OAuth and AWS SigV4 flows, API design against OpenAPI

The honest version

Insomnia pros and cons

No technology is all upside. This is where Insomnia earns its place and where it tends to cause trouble.

Where Insomnia is strong

  • Protocol coverage is wider than PostmanREST, GraphQL, gRPC and WebSockets all behave as first-class protocols rather than aftermarket additions, which matters when you work across them in a single day.
  • Environment hierarchy is sensibleBase, sub-environments and per-request overrides compose cleanly once you understand the precedence, and the UI makes the resolved value visible before you send the request.
  • Git-based sync avoids vendor lock-inYou can store collections in a Git repo your team already owns, which is a relief for anyone who has been burned by a proprietary sync format.
  • OAuth and AWS SigV4 workSeveral flows that are quietly flaky in competitors just work in Insomnia, including SigV4 against regional services and OAuth with PKCE.
  • Scratch Pad for offline workYou can use the full client without an account for personal use, which is how a lot of engineers meet the product in the first place.

Where Insomnia bites

  • Post-acquisition direction keeps shiftingLogin requirements, cloud sync features and the free tier have all changed since the Kong acquisition. Teams who put trust in the 2018 version have been through two or three model changes.
  • Plugin ecosystem is thinnerThere are good plugins, but it is a smaller universe than Postman's and the API has broken between versions more than once.
  • GraphQL schema introspection is strictServers that disable introspection in production show up as broken schemas in Insomnia, which looks like a client bug and is not.
  • Team sync can conflict badlyTwo engineers editing the same request at the same time generates conflicts the UI does not resolve elegantly, and the loser usually loses work.
  • Resource use is high on older machinesInsomnia is an Electron app, and a workspace with thousands of requests takes real memory. Teams on four-year-old laptops notice.
  • Documentation lags the productFeatures land in a release and the docs catch up a month later, which is a problem for new hires trying to learn the tool from scratch.

Sound familiar?

Common Insomnia problems we fix

The Insomnia problems that bring people to us, and what you have once each one is fixed.

insomnia-plugin-sync: push failed, remote has diverged

Team sync is stuck in a conflict

Two engineers edited the same request or environment, both pushed, and the sync plugin cannot merge the result. The branch is now locked and nobody can push until it is resolved.

Sync healthy, team unblocked

OAuth 2.0: refresh_token invalid_grant

OAuth refresh is dying overnight

A refresh token with a shorter lifetime than the saved request's cache, an identity provider that rotated keys, or a client credentials flow that assumed the token never expired.

Auth that refreshes cleanly

Environment variable shadowed by parent folder

Environments bleed across contexts

A parent folder sets _.baseUrl to production, a sub-environment overrides it for staging, and nobody realised the parent won for a specific request type. Calls hit the wrong host.

Environments that do what they say

TLS handshake failed: self signed certificate

Internal APIs refuse to connect

A staging service with a self-signed or private CA certificate, and Insomnia is enforcing validation. The workaround is a per-request toggle, the real fix is importing the CA.

Internal TLS handled properly

AWS Signature Version 4 missing session token

SigV4 against STS credentials fails

Temporary credentials from STS need the session token header as well, which is a separate field in the SigV4 auth helper. A missing one causes a signed request that the service rejects.

SigV4 signing that matches STS

gRPC: reflection not supported by server

gRPC calls will not resolve

The server has reflection disabled in production, so Insomnia cannot discover the service. You have to upload the .proto file manually, which requires getting it from the engineers who own the service.

gRPC workspace with protos in Git

Request template: _.apiKey is undefined

Templated variables resolve to blank

A variable defined in a sub-environment that is not active, or a typo in a nested reference. The request sends an empty Authorization header and the server returns 401.

Templates that always resolve

What we do

Insomnia help, from workspace rescue to upkeep

Call us for one stuck OAuth flow, or let us take the Insomnia workspace and leave it in a shape your team can live with.

Rescue
Sync conflicts, OAuth refresh loops, or environments silently hitting production. We stabilise the workspace first.
Workspace hygiene
Environments split cleanly, folders organised by service, variables scoped so staging does not see production, and templates that always resolve.
Auth flows
OAuth 2.0 with PKCE, AWS SigV4 against STS, mutual TLS and API key schemes wired up so the auth stops being the hard part of a reproduction.
Git sync migration
Moving from Kong Cloud sync to Git-based sync, or the other way, without losing environments or collaborators mid-move.
Managed Tech
Ongoing watch on sync health, workspace structure kept tidy as the API surface grows, plugin updates reviewed before they land, and a person to call when a flow breaks the night before a demo.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Insomnia alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Insomnia questions

Something else? Call+1 737 727 7327

Should we use Insomnia or Postman?

Both work. Insomnia tends to feel lighter, has better gRPC and GraphQL out of the box, and offers Git sync for people who do not want a proprietary cloud. Postman has a larger community and more integrations. If your team already has strong feelings either way, that answer usually wins. If not, the gRPC and Git sync tip the scale toward Insomnia for API-heavy backends.

Why does our OAuth refresh keep failing in Insomnia?

Usually a token lifetime mismatch. The access token is cached for its stated lifetime, but the refresh token lifetime is shorter, so by the time Insomnia tries to refresh the whole flow is dead. Setting a shorter cache horizon, or using the client credentials grant for service tests, handles it cleanly.

Can Insomnia test gRPC services?

Yes, as a first-class protocol. Reflection works if the server exposes it in the environment you are testing. In production where reflection is usually off, you upload the .proto files manually. Keeping those protos in a Git-synced workspace is the way to avoid stale copies.

How do we move from Kong Cloud sync to Git sync?

Export each workspace as a design document, commit it to a Git repo your team owns, and point Insomnia at the repo. The tricky part is environments, which need to be split between what is safe to commit and what belongs in a secret store rather than a public history.

Does Insomnia work offline?

The Scratch Pad tier works fully offline, and even logged-in use is mostly local, with sync happening when the network is available. The gotcha is that some newer cloud features only exist on account tiers, so an offline-first team should pick the Scratch Pad or Git sync workflow.

How much does Insomnia help cost?

The quote is free. Send over the workspace and what is going wrong, and we return a price before any work starts.

Free estimate

Insomnia workspace a mess?

Send over the workspace size, which flows are broken and how your team syncs. A real person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.