Skip to main content

Introduction

TagShape holds configuration for you and answers the question "what is this variable, here?"

The "here" is the whole point. A connection string is not one value — it is a different value in production than in test, a different one again in the EU than in the US, and possibly a different one for a particular customer. Most configuration systems make you model that as separate files, separate keys, or a naming convention that nobody remembers. TagShape models it as tags: you store the value once for each combination that genuinely differs, tag each one with what makes it differ, and ask for it by tag at the moment you need it.

GET /variablevalues?set=1&tag=Environment/Production&tag=Region/EU
{
  "total": 3,
  "items": {
    "DatabaseConnection": "Server=eu-prod.internal;Database=orders",
    "LogLevel": "Warning",
    "FeatureFlags": "checkout-v2"
  }
}

What is in the box​

TagShape is four HTTP services and two web front ends.

PieceWhat it does
Library set APIThe library itself: tag groups, tags, library sets, variables, values, and the endpoint that resolves them.
Account APIOrganizations, users, groups, permissions and API keys.
Identity APIMints and renews JWTs, and exchanges API keys for them.
Audit APIAn append-only record of what changed, who changed it, and what it looked like before and after.
Auth UIThe login page. Branded per organization, backed by the organization's own identity providers.
Management UIWhere a person administers all of the above.

See Architecture for how they talk to each other.

The shape of the model​

Four things, and one rule that connects them.

Tag groups are the dimensions your configuration varies along — Environment, Region, Tier. Tags are the values within a dimension — Production, Staging, EU, US. A tag is always written as Group/Tag, which is what makes Environment/Production unambiguous when someone later adds a Deployment/Production.

Library sets are the groupings you fetch as a unit — one per application, per service, per team, however you like. Variables live inside a library set and have a name. A variable holds one or more values, and each value carries the tags under which it applies. A value with no tags is the default.

The rule is resolution: given a set of tags, the value whose tags match the most of them wins, and the untagged value is the fallback when nothing else matches.

Getting a token​

Nothing in TagShape answers without one. There are two ways to get one:

  • A person signs in through their organization's identity provider — Microsoft Entra ID or Google — and the identity API mints a JWT carrying their permissions. See Identity providers.
  • A machine — a deployment script, a scheduled job, an integration — presents an API key and is handed back a JWT that carries exactly the same claims. Nothing downstream can tell the difference.

The token travels in the x-tagshape-auth header, or in a cookie of the same name for browser requests.

What a caller may do​

Every endpoint declares the permissions it needs, and one piece of middleware enforces all of them. Permissions are granted to groups, and people are members of groups; nobody holds a permission directly.

The permission list is not long, but the way it composes is worth understanding — particularly that permissions can depend on one another, and that being able to grant a permission is a separate question from being able to use it.

API permissions is the page to read: every endpoint in the product, and exactly what it asks for.

Where to go next​