> For the complete documentation index, see [llms.txt](https://docs.erathos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.erathos.com/api/introduction/set-up-connections.md). # Set up connections Set up a workspace's connections, jobs and destination through the API, from choosing a connector to the first run. {% hint style="info" %} This feature is in Beta. {% endhint %} Everything you set up in the platform — a connection, its jobs, the workspace's destination — can also be set up through the API. This lets you build Erathos into your own product: for example, to create a connection for each of your customers from your own onboarding flow, without them ever opening the platform. The setup follows the same steps as in the platform: 1. [**Find your workspace**](#1-find-your-workspace) 2. [**Create a connection**](#2-create-a-connection) and send its credentials 3. [**Configure its jobs**](#3-configure-its-jobs) — the tables or endpoints to sync, and how 4. [**Create the destination**](#4-create-the-destination) the data is loaded into 5. [**Run the jobs**](#5-run-the-jobs) and follow their runs ## Before you start * **Authentication.** Every request carries an API key in the `Authorization` header (`Api-Key `). See [Authentication](/api/concepts/authentication.md). The key acts as its user: each request needs the permissions that user has in the workspace. * **Plan.** The setup endpoints need the **Developer API** feature in the workspace's plan. Without it, they answer `402 Payment Required`. * **Errors.** When a step can't go ahead — the credentials aren't valid yet, a setting is missing, the connector isn't available — the API answers `400` with a `message` that says what to do next. The examples below use `https://api.erathos.com` and these variables: ```bash export ERATHOS_API_KEY="" export WORKSPACE_ID="" ``` ## 1. Find your workspace Connections are created in an existing workspace. List the workspaces the API key's user belongs to and take the `_id` of the one to use: ```bash curl https://api.erathos.com/developers/workspaces/ \ -H "Authorization: Api-Key $ERATHOS_API_KEY" ``` See [Workspaces](/api/api-reference/workspaces.md). ## 2. Create a connection ### Choose a connector A connection is created on a **connector** — the type of data source, such as HubSpot or PostgreSQL. List the connectors the workspace can use (filter with `name`, `is_api` or `is_database`): ```bash curl "https://api.erathos.com/developers/workspaces/$WORKSPACE_ID/source-connectors/?name=hubspot" \ -H "Authorization: Api-Key $ERATHOS_API_KEY" ``` A connector's detail lists the credentials a connection on it takes, so you can collect them before creating anything: * `auth_fields` and `advanced_auth_fields`: values such as a host, a user or an API token. `is_required` says which are mandatory; `is_hidden` marks a secret, whose value is never returned. * `connector_files`: files such as a certificate or a service account key. * `oauth_fields`: accounts the end user signs in to with the provider (see [OAuth](#oauth)). ```bash curl https://api.erathos.com/developers/workspaces/$WORKSPACE_ID/source-connectors// \ -H "Authorization: Api-Key $ERATHOS_API_KEY" ``` ### Create it ```bash curl -X POST https://api.erathos.com/developers/workspaces/$WORKSPACE_ID/connections/ \ -H "Authorization: Api-Key $ERATHOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"connector_id": "", "name": "HubSpot - Acme"}' ``` The connection is created without credentials. The response is the connection as [Get connection](/api/api-reference/connections.md#connections) returns it, with `setup_status: awaiting_credentials`. Keep its `connection_id` for every step that follows. ### Send its credentials Send the values by their field `_id`. Files go base64-encoded. The first time, send every required field. After that, only what you send changes: a field left out keeps its saved value, so you can also use this to replace a single expired token later. ```bash curl -X PATCH https://api.erathos.com/developers/workspaces/$WORKSPACE_ID/connections//credentials/ \ -H "Authorization: Api-Key $ERATHOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "auth_fields": [ {"_id": "", "value": ""} ], "connector_files": [ {"_id": "", "filename": "key.json", "value": ""} ] }' ``` The credentials are checked in the background: `has_valid_credentials` is `null` until the check finishes, then `true` or `false`. #### OAuth Some connectors don't take a token: the end user signs in with the provider instead. For each of the connection's `oauth_fields`, start an authorization: ```bash curl -X POST https://api.erathos.com/developers/workspaces/$WORKSPACE_ID/connections//oauth//authorizations/ \ -H "Authorization: Api-Key $ERATHOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"return_url": "https://app.example.com/erathos/callback"}' ``` Send the end user to the `authorization_url` in the response. They sign in with the provider, Erathos receives the authorization and saves it on the connection, and then: * **With a `return_url`**, the end user is sent back to it, with `status` (`success` or `error`), `connection_id`, `authorization_id` and, on failure, an `error` code added to its query string. The `return_url` must use `https` (`http` is accepted only for `localhost`). * **Without one**, they see a page saying the authorization is done and they can close the window. The `authorization_url` is valid for 30 minutes and can be used once. You can also follow the authorization's `status` (`pending`, `success` or `error`) with [Get OAuth authorization](/api/api-reference/connections.md#credentials). {% hint style="info" %} For a connector that uses your own OAuth app, save the app's credentials (its `auth_fields`, such as its client id) before starting the authorization. Until then, starting one answers `400` with the fields still missing. {% endhint %} ### Follow the setup status A connection's `setup_status` says which step is next. Poll it after sending credentials or settings: ```bash curl https://api.erathos.com/developers/workspaces/$WORKSPACE_ID/connections// \ -H "Authorization: Api-Key $ERATHOS_API_KEY" ``` | `setup_status` | What to do | | ---------------------- | ---------------------------------------------------------------------------------------------------------- | | `awaiting_credentials` | Send the credentials. | | `validating` | Wait: a background check is running, such as reading the source's tables. `running_validation` says which. | | `lost_authentication` | The credentials stopped working: send new ones. | | `needs_settings` | Choose the connection's settings. | | `no_options_available` | The credentials give access to nothing to choose for a setting (e.g. no ad account). | | `schema_unavailable` | The source's tables or endpoints couldn't be read, or none were found. | | `ready_for_jobs` | Configure its jobs. | | `no_destination` | The jobs are set up, but the workspace has no working destination yet. | | `configured` | All set. | ### Choose its settings Some connectors need a choice before their data can be read — for example, which ad account or which spreadsheet. List them once the credentials are valid: ```bash curl https://api.erathos.com/developers/workspaces/$WORKSPACE_ID/connections//settings/ \ -H "Authorization: Api-Key $ERATHOS_API_KEY" ``` For a choice setting, `options` lists what can be picked (paged per setting with `limit`/`offset`; `name` searches them). Then send every required setting: ```bash curl -X POST https://api.erathos.com/developers/workspaces/$WORKSPACE_ID/connections//settings/ \ -H "Authorization: Api-Key $ERATHOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"settings": [{"setting_id": "", "values": ["