Authenticating to API

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.

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 in the EU (default), or https://multi-tenant.sombra.us.transcend.io in the US.
• If you are self-hosting Sombra, you assign this value.

Under Infrastructure > Developer Tools > API Keys 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 integrations, which will change the scopes to manage the data in that integration.

When you add a new integration, you will have the option to issue a new API key or assign the scope for that integration to an existing API key.

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}}

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}}

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. You can also use the filter view to see all of your stale or old API keys.

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

1. Duplicate an existing key

   

2. Swap out the new key for the old key in your next deployment

3. Delete the old key

Security Tip: Never commit your API keys and cycle them regularly

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