Authentication

Every request is authenticated with an API key belonging to an account. The key both identifies the account and scopes what it can see.

Obtaining a key

There’s no public sign-up endpoint — every endpoint, including account creation, requires a key. For now, contact TAGBASE to get a master account and its API keys. That master account and key are your starting credential.

From there you’re self-service for tenants: use your master key to create a subaccount for each customer or tenant, and the response hands back that subaccount’s own key. So you get your master account and key from TAGBASE to begin with, and mint the rest yourself.

Key format

A key is two parts joined by a colon — a public key id and a secret:

key_abcdef0123456789:superstrongrandomsecret

You receive the full string once, when the key is minted (see Accounts). The platform stores only a hash of the secret and can never show it to you again. Treat the whole string as a credential: store it somewhere secret, never commit it, never put it in a URL.

Sending the key

Pass the full key_id:secret string as a bearer token:

curl https://platform.tagbase.io/api/v1/tags \
  -X POST \
  -H "Authorization: Bearer key_abcdef0123456789:superstrongrandomsecret" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{ "data": { "type": "tags", "attributes": { "protocol": "<protocol>", "count": 1 } } }'

await fetch("https://platform.tagbase.io/api/v1/tags", {
  method: "POST",
  headers: {
    "Authorization": "Bearer key_abcdef0123456789:superstrongrandomsecret",
    "Content-Type": "application/vnd.api+json",
  },
  body: JSON.stringify({
    data: { type: "tags", attributes: { protocol: "<protocol>", count: 1 } },
  }),
});

$client->post("https://platform.tagbase.io/api/v1/tags", [
    "headers" => [
        "Authorization" => "Bearer key_abcdef0123456789:superstrongrandomsecret",
        "Content-Type"  => "application/vnd.api+json",
    ],
    "json" => [
        "data" => ["type" => "tags", "attributes" => ["protocol" => "<protocol>", "count" => 1]],
    ],
]);

Req.post!("https://platform.tagbase.io/api/v1/tags",
  headers: [
    {"authorization", "Bearer key_abcdef0123456789:superstrongrandomsecret"},
    {"content-type", "application/vnd.api+json"}
  ],
  json: %{data: %{type: "tags", attributes: %{protocol: "<protocol>", count: 1}}}
)

Scope

A key sees only its own account’s resources. This is the isolation boundary for subaccounts: a subaccount’s key can create and verify tags under that subaccount and nothing else. Presenting a key for a tag owned by a different account returns 404 Not Found — the platform doesn’t distinguish “not yours” from “doesn’t exist”.

Auth errors

A missing, malformed, revoked, or unrecognized key returns 401:

{
  "errors": [
    { "status": "401", "title": "Unauthorized" }
  ]
}

This covers every failure mode — no Authorization header, a header that isn’t Bearer <key_id>:<secret>, a secret that doesn’t match, or a key that has been revoked.

Rotation

Each account can hold more than one active key, so you can rotate without downtime: provision the replacement, move your traffic over, then retire the old one.

Self-service key management endpoints (create / list / revoke a key on an existing account) are not part of the public API yet — today a key is minted together with its account. Until they ship, rotation on an existing account is handled by TAGBASE. Plan key storage so swapping the value is a config change on your side.