Telescope API

English

Norsk

English

Norsk

Appearance

Authentication ​

Every request needs an API key in the X-API-Key header:

sh
curl -H "X-API-Key: tel_AbCd1234_..." https://api.telescope.eco/external/properties/

Create an API key ​

  1. Sign in to Telescope.
  2. Open Account settings → API keys.
  3. Click Create API key and give it a name that says where it is used, such as Power BI - Finance or Data warehouse.
  4. Copy the secret. It is shown only once. Store it in a password manager or your platform's secret store.
Account settings, API keys page with the Create API key button
The dialog showing a new API key secret with the Copy button

A key looks like tel_AbCd1234_ followed by 32 letters and digits. The first part (tel_AbCd1234) is the key's prefix, which the API keys page shows so you can tell your keys apart. Telescope only stores a hash of the secret, so a lost secret can't be recovered. Rotate the key instead.

Whose data a key sees ​

A key belongs to the user who created it and acts on their behalf:

  • It sees the data of that user's organization, and nothing else.
  • If the user moves to another organization, the key follows them.
  • If the user is deactivated, the key stops working.

So create integration keys from an account that will stay in the organization, and give each integration its own key. You can then rotate or revoke one integration without touching the others.

Reading is open to every organization. Creating properties must also be enabled for your organization by Telescope.

Rotate, rename or revoke a key ​

On the API keys page you can:

  • Rotate a key. Telescope creates a new secret and the old one stops working immediately. Update every system that uses the key right away.
  • Rename a key. The secret stays the same.
  • Revoke a key. Requests with it fail from then on.

The page also shows when each key was last used, which helps you find keys that nothing uses anymore.

When authentication fails ​

A missing, wrong, rotated or revoked key returns 401 Unauthorized:

json
{ "detail": "Invalid API key.", "code": "authentication_failed" }

Without the header at all, detail is An API key must be included in X-API-Key.

Keep keys safe ​

  • Send keys only to https://api.telescope.eco (or staging). Never put them in URLs, since URLs end up in logs.
  • Don't commit keys to source control or paste them into shared documents.
  • Anyone who can edit a Power BI file that contains a key can read it. See Power BI security.
  • If a key may have leaked, rotate it.