Slug Addressing
Every org and every project on Kilimanjaro has a customer-friendly slug — a short, memorable, org-scoped identifier the customer picks at creation. Slugs are the canonical form for customer-facing surfaces: URLs, SDK init configuration, CLI commands, dashboards, error messages, support tickets. The internal database identifier is still there — webhook payloads and audit-ledger entries surface both — but the slug is what humans type and what URLs carry.
1. What a slug is
A slug is a short string conforming to the format [a-z][a-z0-9-]{1,62}:
- Lowercase alphanumeric with hyphens
- Starts with a letter
- 2 to 63 characters total
- No double hyphens, no leading or trailing hyphen
- DNS-label compatible (so the org slug can carry through to the subdomain in
<orgSlug>.api.k9o.io)
Examples: acme, formelo, partner-console-staging, shop, partners.
The two-tier identity has matching slugs:
| Identifier | Scope | Example |
|---|---|---|
| Org slug | Platform-globally unique | acme |
| Project slug | Unique within the owning org | shop (under acme) |
The canonical short-form a customer reads and writes is <orgSlug>/<projectSlug> — for example, acme/shop or formelo/partner-console-staging.
2. Slugs are the customer surface
Slugs carry three properties:
- Developer experience.
acme.api.k9o.io/@shop/data/ordersis something a developer types, remembers, and discusses. - Brand sovereignty. The customer's slug appears in every URL their end-users see — the customer's brand on the URL, not an opaque identifier.
- Operational clarity. Logs, support tickets, dashboards, and error messages identify the right org and project unambiguously.
IDs (org_<base62>, proj_<base62>) remain the internal join key — immutable handles for audit forensics and cross-system references. Customer-facing surfaces lead with the slug.
3. Slug versus ID — composition rule
Every customer-facing surface uses the slug. Every internal record carries the ID. Where the two meet — webhook payloads, audit-ledger entries, error responses — both are present as separate JSON fields:
{
"event_id": "evt_a8B3cD9eF2",
"org": { "id": "org_xxx", "slug": "acme" },
"project": { "id": "proj_xxx", "slug": "shop" },
"...": "..."
}
Downstream consumers join on id for stable cross-system reference; humans read slug for context. Either form resolves the same record.
4. Rename semantics — immediate and breaking
A slug rename is a customer-initiated operation on the org or project. The platform updates the slug record immediately and surfaces the new slug everywhere. The rename is a breaking change for any caller that hard-coded the old slug:
- Requests against the old slug receive
K9O_SLUG_GONE(HTTP 410 Gone). The tombstone payload carries{ gone_slug, renamed_at }— there is no redirect, no 301, and no grace period; the caller is responsible for updating any hard-coded reference. - Webhook subscriptions that filter on slug must be reconfigured
- API keys remain valid (they bind to the ID, not the slug)
- Audit-ledger entries from before the rename retain the old slug in their JSON; the underlying
idfield continues to resolve correctly
A slug rename is rare and intentional — rebrand, ownership transfer, structural cleanup. K9O_SLUG_GONE surfaces the change loudly; the customer updates any integration that hard-coded the prior slug.
The old slug does not return to the available pool. It moves to a reserved state — see §5 below.
5. Reservation discipline
A slug enters the reserved pool when one of three things happens:
| Event | Effect |
|---|---|
| Slug is on the platform reserved-word seed list | Cannot be claimed; returns K9O_SLUG_RESERVED |
| Slug was previously assigned and then released (rename or deletion) | Moves to reserved; cannot be re-claimed by default |
| Slug is brand-protected | Cannot be claimed by callers other than the brand owner |
The reserved-word seed protects the platform's own brand surface — kilimanjaro, paperless, context, lookout, gate-studio, kibo, gate, console, admin, auth, and similar terms cannot be claimed by customer orgs. The protection is bidirectional: it prevents accidental brand collision in URLs, and it preserves slugs the platform reserves for its own surfaces.
Released slugs (from rename or deletion) enter the reserved pool to prevent a confusing recycling pattern where a slug a previous customer used could be re-claimed by an unrelated party. A previous customer's acme/shop will not become a new customer's acme/shop by default. The platform retains administrative discretion to resurrect a slug back to the available pool — typically on the prior owner's request when the original deletion was inadvertent — but the default posture is reservation.
6. Brand-protected slugs
The reservation discipline extends to brand-protected slugs: terms whose customer-facing appearance would create real brand confusion (third-party trademarks the platform recognises, regulated names, the platform's own names). These slugs are reserved with a manual administrative override path — not freely claimable, not algorithmically claimable, but resurrectable by the legitimate brand owner through a verification process.
This is a positive trust mechanism: a customer searching for stripe/integrations cannot accidentally land on a slug squatter's project, and Stripe (in this hypothetical) can be confident that the slug is held for them.
7. Slug errors
The slug subsystem coins these error codes:
| Code | Status | Condition |
|---|---|---|
K9O_SLUG_RESERVED | 400 | Claim attempt against a reserved (seed-list or brand-protected) slug |
K9O_SLUG_TAKEN | 409 | Claim attempt against a slug already held by a live resource |
K9O_SLUG_INVALID_FORMAT | 400 | Slug fails the [a-z][a-z0-9-]{1,62} format check |
K9O_SLUG_GONE | 410 | Request hit an old slug after a rename; the tombstone carries { gone_slug, renamed_at } |
K9O_ORG_NOT_FOUND | 404 | The org-labelled host resolves to no live org (typo or wrong org) |
Each error body carries remediation context — K9O_SLUG_GONE carries { gone_slug, renamed_at } (no redirect; the caller updates its own references); K9O_SLUG_RESERVED includes the reason category (seed-list / post-deletion / brand-protected).
8. See also
- Routing Modes — how slugs compose into URLs across the platform's three deployment routing modes.
- Session Model — root-domain and tenant-subdomain sessions; how the slug carries through the exchange flow.
- Custom Domains — a capability of every project that lets customers replace the platform subdomain with their own.
- Architecture → Overview — where slugs sit in the broader platform model.