Account setup and authentication

How to get Vantage API access, authenticate your requests, and configure the webhook endpoint that receives order and result updates.

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).

Your credentials will initially only work against the sandbox environment (https://vantage-sandbox.tryterra.co). Production access is enabled separately.

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). You can present them in either of two ways:

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

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

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:

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.

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:

cURL

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

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)

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

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.

Once your webhook endpoint is configured, you are ready for Ordering your first test.