Onboard clients

Teak sells protection under a client: the business the customer is buying from. If you're a partner, a platform such as a ticketing system that sells for several businesses, create a client in Teak for each of them. Each client gets its own API keys, which you use for its widget and orders. You can also create clients by hand in the Teak Dashboard. This page covers creating them from your platform, with the API.

If you sell only for yourself, your account is already a client with its own keys, and you can skip this page.

Partner and client keys

As a partner, you have your own keys, and each client you create has its own:

Keys	Use them for
Partner keys	Onboard a client, and nothing else
Client keys	Everything for that client: the widget's `apiKey`, and the access tokens your server uses to submit, look up, void, and cancel the client's orders

Using the wrong keys fails. Onboarding with a client's keys returns error.code 403, and a session created with one client's public key can't be submitted with another's keys.

Before you start

You need, from your Teak integration contact:

Your partner keys for sandbox: a public key (pk_...) and a secret key (sk_...).
Your partner ID (af_...). It's also under Settings in the Teak Dashboard. The API calls it affiliate.
The product name each client offers, exactly as your contact gives it, for example Optional RaaS.

1. Get an access token with your partner keys

Create an access token with your partner keys, not a client's:

const TEAK_API = 'https://api.sandbox.helloteak.com/v1';

async function getPartnerToken() {
  const res = await fetch(`${TEAK_API}/auth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      public_key: process.env.TEAK_PARTNER_PUBLIC_KEY,
      secret_key: process.env.TEAK_PARTNER_SECRET_KEY,
    }),
  });
  if (!res.ok) throw new Error(`Teak auth failed: ${res.status}`);
  return (await res.json()).token;
}

import os

import requests

TEAK_API = "https://api.sandbox.helloteak.com/v1"


def get_partner_token():
    res = requests.post(
        f"{TEAK_API}/auth/token",
        json={
            "public_key": os.environ["TEAK_PARTNER_PUBLIC_KEY"],
            "secret_key": os.environ["TEAK_PARTNER_SECRET_KEY"],
        },
        timeout=10,
    )
    res.raise_for_status()
    return res.json()["token"]

curl -X POST https://api.sandbox.helloteak.com/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"public_key": "pk_...", "secret_key": "sk_..."}'

2. Create the client

Call Onboard a client with the client's details:

async function onboardClient(business) {
  const res = await fetch(`${TEAK_API}/accounts`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${await getPartnerToken()}`,
    },
    body: JSON.stringify({
      name: business.name,                         // as customers see it
      affiliate: process.env.TEAK_PARTNER_ID,      // your partner ID, af_...
      product: 'Optional RaaS',                    // from your Teak integration contact
      domain: business.domain,
      user: { email: business.adminEmail },        // optional: a Teak Dashboard login
      send_activation: true,
    }),
  });
  if (!res.ok) throw new Error(`Teak onboarding failed: ${res.status} ${await res.text()}`);
  return res.json();
}

# business is your own record of the client
def onboard_client(business):
    res = requests.post(
        f"{TEAK_API}/accounts",
        headers={"Authorization": f"Bearer {get_partner_token()}"},
        json={
            "name": business["name"],                     # as customers see it
            "affiliate": os.environ["TEAK_PARTNER_ID"],   # your partner ID, af_...
            "product": "Optional RaaS",                   # from your Teak integration contact
            "domain": business["domain"],
            "user": {"email": business["admin_email"]},   # optional: a Teak Dashboard login
            "send_activation": True,
        },
        timeout=10,
    )
    if not res.ok:
        raise RuntimeError(f"Teak onboarding failed: {res.status_code} {res.text}")
    return res.json()

curl -X POST https://api.sandbox.helloteak.com/v1/accounts \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "name": "Summer Fest",
    "affiliate": "af_3M4eN3fv",
    "product": "Optional RaaS",
    "domain": "summerfest.example.com",
    "user": {"email": "[email protected]"},
    "send_activation": true
  }'

Field	Required	Description
`name`	Yes	The client's name, as customers see it. It must be unique across Teak.
`affiliate`	Yes	Your partner ID (`af_...`).
`product`	Yes	The protection product the client offers, exactly as your Teak integration contact gives it.
`domain`		The client's website domain.
`user.email`		Someone to give access to the client in the Teak Dashboard, where they can see orders and manage webhooks. The email must not already have a Teak Dashboard account.
`send_activation`		`true` to email `user` a link to activate their account.

Teak responds with the new client and its keys:

{
  "id": "cl_HX5tUe9m",
  "name": "Summer Fest",
  "domain": "summerfest.example.com",
  "affiliate": "af_3M4eN3fv",
  "owner": "usr_1uUixeBO",
  "products": ["Optional RaaS"],
  "api_keys": {
    "public_key": "pk_sandbox_...",
    "secret_key": "sk_sandbox_..."
  }
}

This is the only time you get the client's secret key

Store both keys straight away, in your secret manager, against the business in your system. If the secret key is lost or exposed, contact your Teak integration contact to replace it.

3. Use the client's keys

For everything else, use the client's own keys:

In the widget, pass the client's public key as apiKey on that client's checkout pages. See Add the widget.
On your server, get access tokens with the client's public and secret keys to submit its orders, and to look up, void, or cancel them.

Keep a record of which Teak client ID and keys belong to each business, so every checkout uses the right ones. Sandbox and production are separate: onboard each client in both, and store both sets of keys.

Handle errors

The errors you're most likely to see:

Error	What to do
`error.code` `403`: `You must be an affiliate admin to access this resource.`	You used a client's keys. Get the token with your partner keys.
`.affiliate - Object with resource id=... does not exist`	Check your partner ID, and that it's for the same environment as your keys.
`.product - Value given does not match an actual product`, or a product that isn't available to your partner account	Use the product name exactly as your Teak integration contact gave it.
`.slug - Client with this slug already exists`	A client with this name already exists in Teak. Use a different name, or check whether you've already onboarded this business.
`user.email - User with this email already exists`	That person already has a Teak Dashboard account. Leave out `user`, or use a different email.
HTTP `422` with a `detail` list	A required field is missing. `detail[].loc` names it.

Every error, with its exact response, is in the Onboard a client reference. Don't retry these unchanged: fix the request first. See Error handling.

Next steps

With a client onboarded, set up its checkout:

Follow the integration guide with the client's keys, from sandbox to live.
Subscribe to webhooks. Subscriptions set up at the partner level send you events for every client.