Authentication

Every request carries your key in the x-api-key header. The key is all you need to authenticate. You do not sign in, trade it for a token or keep a session alive.

curl "https://api.insightsocial.app/v1/instagram/profile?handle=natgeo" \
  -H "x-api-key: $INSIGHTSOCIAL_API_KEY"

What a key looks like

A key is isk_live_ followed by 43 URL-safe characters (32 random bytes). You may also come across keys starting isk_test_. They are accepted the same way and draw on the same credits.

Because we keep only a hash, the full key is visible a single time: in the dialog that opens right after you create it. Nobody at InsightSocial can read it back to you. Save it to your secret store while the dialog is still open.

Create a key

1. Sign in at insightsocial.app.
2. Open API keys in the dashboard. The first time you open the API section, a first key is created for you.
3. To add another, click create and give it a name that says where it runs, such as production or local-dev. A name is required and can be up to 64 characters.
4. Copy the key from the one-time dialog.

Send the key

curl "https://api.insightsocial.app/v1/instagram/profile?handle=natgeo" \
  -H "x-api-key: $INSIGHTSOCIAL_API_KEY"

Authentication errors

Authentication runs before anything else, so these failures never cost credits and do not count against your rate limit. credits_remaining is null on all of them.

{
  "success": false,
  "error": {
    "type": "API_KEY_REVOKED",
    "message": "This API key has been revoked. Create a new one at https://www.insightsocial.app/portal/api/keys"
  },
  "request_id": "req_1a2b3c4d5e6f",
  "credits_used": 0,
  "credits_remaining": null
}

The 401s are not worth retrying: the same key fails the same way until you change it. Running out of credits is a different problem and returns 402 INSUFFICIENT_CREDITS; see Errors.

Key management

Rotate a key

Issue the new key, roll it out, check that requests now use it, and only then revoke the old one from the dashboard. Revoking first causes downtime, because the old key stops working on its very next request.

If a key has leaked, revoke it at once and accept the downtime. Anyone holding a live key can spend your credits.

Security guidance

• Never ship a key in client-side code. Anyone can unpack a web or mobile app and pull the key out, and you pay for every call made with it. Put a server route in front of the API.
• Use one key per environment. That way you can revoke a test key without breaking live traffic.
• Store keys in a secret manager or encrypted environment variables, never in git.
• Revoke keys you no longer use, including ones issued to contractors or short-lived jobs.

Next steps