Skip to content
Bifröst OrbitDocs

API keys

Make a key that sends events from your servers, reads raw events for your own tools, or both, and remove it when it is no longer used.

How-to guide2 min read

An API key lets a server or data tool talk to Insights Orbit for your organisation. The script needs no key: it uses the site key, which is not a secret.

Make a key

  1. An Admin opens API keys under Developers and selects New API key.
  2. Give it a Name after what will use it, such as Booking server or Data warehouse.
  3. Under What it may do, tick one or both:
    • Send events: events that happen on your servers, such as a payment, sent to the server API. Every plan.
    • Read events: every raw event of every site, through the raw event API, GraphQL and the API playground. Growth plan and up.
  4. Select Make the key, then copy it under Copy the key now.

The key starts with ins_live_ and is shown only once. Insights Orbit keeps only a scrambled form, so it can't show it again. Keep it in your server's or tool's settings, never in a web page or an app.

A key belongs to the organisation, not to one site: the site is chosen in each request. Make one key per server or tool, so you can remove one without stopping the others.

Use a key

Send it in the Authorization header:

Shell
curl "https://api.bifrostorbit.com/insights/v1/events?site=SITE_KEY" \  -H "Authorization: Bearer ins_live_…"

GraphQL also takes it as x-api-key. A key used for something it may not do is refused with 403 and wrong_scope.

See and remove keys

API keys lists every key with its name, the start of the key, what it May do, when it was Made and when it was Last used. Select Remove, then Remove the key, to stop it at once. This can't be undone; make a new key if you need one again.

Only Admins see API keys. Making and removing keys is in the audit trail.

Limits

Sending events
Per key, per minute
600 requests
Reading raw events
Per key, per minute
60 requests
GraphQL
Per key, per minute
60 requests, counted apart from raw events

Over the limit, requests answer 429. Wait a minute, or send more events in each request.

Was this page helpful?

Read next

Send events from a serverSend events that happen on your servers, such as payments, with an API key, so they count in goals and funnels next to website events.Read raw eventsRead every event your sites collected, page by page, with an API key, for your own data tools.GraphQLRead a site's raw events through GraphQL, with the same keys, limits and plan as the raw event API, and the schema, examples and errors.The API playgroundRead your sites' raw events through REST and GraphQL from your browser, see the JSON, and copy the request as curl or JavaScript.