> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/vantage-api-docs/account-setup-and-api-keys.md).

# Account setup and authentication

Vantage API onboarding is currently done manually. In short:

1. Contact the Terra API team (or your existing Terra contact) to request access.
2. Vantage is enabled on your Terra credentials - **sandbox first**. (New to Terra API? You'll receive a `dev-id` and API key as part of onboarding.)
3. Configure your webhook endpoint (below) and start building in sandbox. Commercial terms and production access are arranged when you are ready to go live (see [Going to production](/vantage-api-docs/important-information/going-to-production.md)).

{% hint style="info" %}
Your credentials will initially only work against the sandbox environment (`https://vantage-sandbox.tryterra.co`). Production access is enabled separately.
{% endhint %}

## Authentication

Vantage API uses your standard Terra API credentials - the same `dev-id` and API key you use with other Terra API products (visible in your [Terra dashboard](https://dashboard.tryterra.co)). You can present them in either of two ways:

**Option 1 - HTTP Basic auth (recommended).** Username = your `dev-id`, password = your API key:

```bash
curl 'https://vantage-sandbox.tryterra.co/api/v1/products' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'
```

`curl -u` builds the header for you. If your HTTP client does not, base64-encode `dev-id:api-key` yourself and send it as `Authorization: Basic <encoded>`:

```bash
echo -n 'YOUR_DEV_ID:YOUR_API_KEY' | base64
# then send: Authorization: Basic <output of the command above>
```

**Option 2 - header pair.** The same `dev-id` + `x-api-key` headers used across Terra API:

```bash
curl 'https://vantage-sandbox.tryterra.co/api/v1/products' \
  --header 'dev-id: YOUR_DEV_ID' \
  --header 'x-api-key: YOUR_API_KEY'
```

Both are accepted on every authenticated endpoint. A wrong or unknown credential returns `401`; a suspended account or an account without Vantage access returns `403`. See [Errors](/vantage-api-docs/documentation/errors.md).

## Configure your webhook endpoint

Order and result progress is delivered to a single HTTPS webhook URL per environment (sandbox and production each hold their own). Set it once during setup:

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request PATCH \
  'https://vantage-sandbox.tryterra.co/api/v1/clients/webhook-url' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "webhook_url": "https://your-domain.com/webhooks/terra"
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://vantage-sandbox.tryterra.co/api/v1/clients/webhook-url"

response = requests.patch(
    url,
    auth=("YOUR_DEV_ID", "YOUR_API_KEY"),
    json={"webhook_url": "https://your-domain.com/webhooks/terra"},
)

print(response.status_code)
print(response.text)
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://vantage-sandbox.tryterra.co/api/v1/clients/webhook-url"

	payload := map[string]string{
		"webhook_url": "https://your-domain.com/webhooks/terra",
	}
	jsonData, err := json.Marshal(payload)
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("PATCH", url, bytes.NewBuffer(jsonData))
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth("YOUR_DEV_ID", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(body))
}
```

{% endtab %}
{% endtabs %}

Notes:

* The URL **must be HTTPS**. Sending an empty string (`""`) clears it, which stops webhook delivery.
* `GET /api/v1/clients/webhook-url` returns the currently registered URL for the environment you call it on.
* Webhooks are signed; verify the signature on every delivery. See [Webhooks](/vantage-api-docs/documentation/webhooks.md).

Once your webhook endpoint is configured, you are ready for [Ordering your first test](/vantage-api-docs/getting-started/ordering-your-first-test.md).