Authenticating to API

How to call the Transcend API and authenticate to it.

🚧

Security tip: HTTPS only

All requests must be made over HTTPS. Requests not made over HTTPS will be rejected.

The only exception to this is if you are self-hosting Sombra and explicitly configure Sombra to listen over HTTP.

API base URL

The base URL for the API depends on how you're using the Sombra gateway:

  • If Transcend is hosting Sombra for you, this is https://multi-tenant.sombra.transcend.io.
  • If you are self-hosting Sombra, you assign this value.

Authentication

Creating API Keys

On your Developer Settings tab → you can issue and manage API keys. Each API key can be assigned scopes that dictate what that API key is authorized to do. They can also be assigned to data silos, which scopes the key to manage the data in that silo.

When you add a new Data Silo, you will have the option to issue a new API key or assigning the scope for that data silo to an existing API key.

Authenticating to Transcend

Every request must include an authorization header with a Bearer token which is your Transcend API key. Headers are case-insensitive, so Authorization and authorization are equivalent.

Authorization: Bearer <<apiKey>>

Authenticating to Sombra (self-hosted and single-tenant only)

If you're self-hosting Sombra or Transcend is hosting your single-tenant instance, then every request must include an x-sombra-authorization header with a Bearer token which is your Sombra API INTERNAL_KEY.

x-sombra-authorization: Bearer <<sombraInternalKey>>

Cycling API Keys

These API keys should be treated as secrets. They should never be committed to code and they should be cycled regularly. We will remind you when it is a good time to cycle your keys.

The simplest way to cycle a key is to do the following:

  1. Duplicate an existing key
  1. Swap out the new key for the old key in your next deployment
  2. Delete the old key

🚧

Security Tip: Never commit your API and cycle regularly

You should make sure you manage your API keys strictly. They should be kept in a secure key store.