External API Setup

Obtaining an API Key

In order to make API requests you will need to authenticate with an API key.

You can obtain an API key by going to the Settings page and clicking Generate a new API Key. A list of all created API keys will be shown here.

The page will then display your newly generated API key which you can optionally label. Store it in a secure place because you will not be able to view the entire key again once you leave the page.

Allowed environments

When setting an allowed environment, you have the option to either select an environment or allow all environments. This restricts the API key to only access embeds created in the associated environment.

This also restricts the API key to only push to the associated environment when creating a template. The exception is for an API key associated with the Production environment since pushing to Production will automatically push to all other environments.

Making Requests to OneSchema

API requests are made through the api.oneschema.co subdomain, irrespective of your own organization's subdomain. Requests are authenticated using either the Header X-API-KEY or using HTTP Basic Authentication.

When using the API Key header, use your API key as the value of the X-API-KEY header. When using HTTP Basic Authentication create your Base64 encoded value by encoding your API key as the password, and an empty username, e.g :<API_KEY>

Once you have an API key you can test that it works either by using the "Try It!" playground included in our API reference pages, or by making the following curl request to our whoami endpoint:

API_KEY=RmAXu+...
curl https://api.oneschema.co/whoami -u ":$API_KEY"
{ "org": "Your Company" }

Multi-region hosting

To make requests when using a non-US hosted instance of OneSchema, the base URL of https://api.oneschema.co/ must be modified according to the following table.

Region	Base URL
United States	No change, https://api.oneschema.co/
Canada	https://api.ca.oneschema.co/
Europe	https://api.eu.oneschema.co/
Australia	https://api.au.oneschema.co/
Self-hosted	Custom

Making Requests to Embeds

If you are creating embeds via our Create an Embedded Session API, all of our external API endpoints take in embed_id as a query parameter that can be used to execute the API request in the context of an embed.