Key types
There are two kinds, and picking the right one matters.
Publishable keys: ig_pk_…
For browsers. Goes directly in your page source.
These are public by design. Anyone viewing your page can read the key, and that is expected, the same as a Google Maps JS key or a Stripe publishable key. What stops someone else using it is the origin allowlist.
- Requires at least one allowed origin
- Shown in full in your dashboard whenever you need it
- Safe to commit, safe to ship in a bundle
Secret keys: ig_sk_…
For servers and mobile apps. Anything that does not send an Origin header,
which means the allowlist cannot protect it.
- Shown exactly once, at creation. We store an identifier, not the key. We cannot show it to you again because we do not have it.
- Rate limited per IP
- Treat like a password: environment variables or a secrets vault, never a repo
If you lose one, revoke it and create another. There is no recovery.
Which do I need?
| Calling from | Use |
|---|---|
| A web page | Publishable |
| A Node/Python/Go server | Secret |
| A mobile app | Secret |
| A serverless function | Secret |
| curl, for testing | Either. Publishable works but is rate limited per IP |
The trap when calling from a server
A key answers the question “where is whoever made this request”. Called from a browser that is the visitor, which is what you want. Called from your own backend, the request came from your backend, so you get your datacentre, in whatever region you deploy to. Every field is populated and every field is wrong, which is worse than an error, because nothing looks broken.
Two ways out:
- Ask from the visitor’s browser, with a publishable key. This is the accurate answer, and the one to prefer.
- Ask from your server with a secret key and pass the visitor’s address as
ip=. Convenient, and less accurate. Take the address from the header your own proxy or CDN sets, not from anything a client can put there.
Revocation
Revoking is permanent. It propagates within 30 seconds. The API keeps an in-memory snapshot rather than checking the database on every request, which is what makes it fast. If you are revoking because a key leaked, count those 30 seconds as part of the exposure.
Rotating without downtime
- Create the new key
- Deploy it alongside the old one
- Confirm traffic has moved (the dashboard shows per-key usage)
- Revoke the old key
Never revoke first. There is no grace period.