Accounts

An account owns tags and API keys. The account that owns your key is your master account; accounts you create through the API are subaccounts of it — the unit of multi-tenancy. Creating a subaccount also mints its first API key.

Fields

A subaccount is always created beneath the account whose key you present; you don’t pass a parent — it’s inferred from the key.

Create a subaccount

POST /api/v1/accounts

Request

{
  "data": {
    "type": "accounts",
    "attributes": {
      "name": "Metropolitan Museum — Night Watch"
    }
  }
}

name is the only required attribute. The request also accepts optional profile attributes if you want to store them on the account: company, vat, country, address, city, state, zip_code.

curl https://platform.tagbase.io/api/v1/accounts \
  -X POST \
  -H "Authorization: Bearer $TAGBASE_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{ "data": { "type": "accounts", "attributes": { "name": "Metropolitan Museum — Night Watch" } } }'

const res = await fetch("https://platform.tagbase.io/api/v1/accounts", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TAGBASE_API_KEY}`,
    "Content-Type": "application/vnd.api+json",
  },
  body: JSON.stringify({
    data: { type: "accounts", attributes: { name: "Metropolitan Museum — Night Watch" } },
  }),
});
const account = await res.json();

$response = $client->post("https://platform.tagbase.io/api/v1/accounts", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("TAGBASE_API_KEY"),
        "Content-Type"  => "application/vnd.api+json",
    ],
    "json" => [
        "data" => ["type" => "accounts", "attributes" => ["name" => "Metropolitan Museum — Night Watch"]],
    ],
]);
$account = json_decode((string) $response->getBody(), true);

account =
  Req.post!("https://platform.tagbase.io/api/v1/accounts",
    headers: [
      {"authorization", "Bearer #{System.fetch_env!("TAGBASE_API_KEY")}"},
      {"content-type", "application/vnd.api+json"}
    ],
    json: %{data: %{type: "accounts", attributes: %{name: "Metropolitan Museum — Night Watch"}}}
  ).body

Response — 201 Created

The new subaccount, plus its freshly minted API key as an included api_keys resource. The key’s secret is shown here and nowhere else — capture it now.

{
  "data": {
    "type": "accounts",
    "id": "acc_G5aNFLDZd6es1brCrj7QFi",
    "attributes": { "name": "Metropolitan Museum — Night Watch" },
    "relationships": {
      "api_keys": {
        "data": [ { "type": "api_keys", "id": "key_PD5omomyAxXscwKde4mpUS" } ]
      }
    }
  },
  "included": [
    {
      "type": "api_keys",
      "id": "key_PD5omomyAxXscwKde4mpUS",
      "attributes": { "secret": "key_PD5omomyAxXscwKde4mpUS:MFV6n8TpDjNYfaLH7BE2W4Clyu8UOV6DqM3yFzxhhqs" }
    }
  ]
}

Store included[].attributes.secret immediately — it’s the credential you’ll use for every request made on behalf of this subaccount.

Errors

Notes

• There is no endpoint to read, list, or update an account after creation. Record the returned id and key when you create it.
• Subaccounts nest one level beneath the presenting account; deeper hierarchies aren’t exposed through the API.