API stability
What is stable, and what is not
The Go module follows strict Semantic Versioning, and the document says exactly what counts as public API. The TypeScript core is pre-1.0 at 0.5.0 and carries no stability guarantee yet. Go latest: v2.7.0.
Sources and review date
- Source
- theauth-go stability policy for Go. For TypeScript, MAINTAINERS.md and SECURITY.md in the theauth repository.
- Last reviewed
- 2026-10-06. Summaries on this page are written by hand and checked against the linked documents on that date. The documents themselves are the record.
Go module
Strict SemVer
From v1.0 the module follows Semantic Versioning strictly. The import path is github.com/glincker/theauth-go/v2.
- BreakingChanging a stable symbol's signature, name or documented behavior contract requires a new major version.
- AdditiveNew exported symbols, new optional Config fields and new methods on
*TheAuthare non-breaking. - DeprecationAnnounced one minor version before removal with a // Deprecated: godoc line.
- Not publicAnything under internal/, anything under examples/, test helpers, and the audit writer internals.
Surface
Stable and experimental packages
The document lists stable symbols per package. In summary:
Stable
- Core
- The root package, crypto, email, provider and the individual provider packages, storage, storage/memory, storage/postgres and admin.
- Added in v2.x
- mcpresource (a separately importable, zero-dependency module) and the SIEM audit sinks for Splunk HEC, generic webhook and OTLP.
- Storage capabilities
- The capability interfaces that Storage is composed of, Config.CoreStorage, Handler() and Config.PathPrefix, from v2.6.
Experimental, may change in a minor release
- Packages
- storage/sqlite (a separate module), clientauth and policy.
- OAuth redirect fields
- OAuthConfig.RedirectURI and related fields, OAuthStart and OAuthCallback.
- Other v2.6 additions
- Optional storage capabilities added in v2.6, provider resolver hooks, the doctor tooling, agent identity and revocation helpers, and token import helpers. The document has the exact list.
- Storage interfaceAdding a method to Storage would break implementers, so new persistence operations land behind separate optional interfaces, detected at runtime. The base interface only grows in a major release.
- MigrationsPostgres and MySQL migrations are append-only. A rename ships as a new migration that adds the new column.
- Audit tableaudit_events is append-only by contract. Adapters expose insert and query, not update or delete.
- Stats countersExisting Stats counters keep their name and meaning. New fields are allowed.
- Without a majorBug fixes, performance work that keeps outputs, new optional config, new error sentinels and codes, and new audit actions.
Special rules
What the document pins down
These rules exist so a minor upgrade does not break people who implement or depend on the interfaces.
TypeScript
Pre-1.0, no guarantee yet
Said plainly: the TypeScript packages are not under a stability guarantee.
The core package @glinr/theauth is at 0.5.0. The repository's maintainer guide says packages are versioned independently with Changesets and that most are pre-1.0, so minor bumps may include breaking changes, which are called out in the changeset.
Its security policy gives the supported release line per package, and security fixes go to the latest line only. Pin versions and read release notes before upgrading. See SECURITY.md for the current table.
What we do not claim
- No guarantee for TypeScript. Until 1.0, treat every minor release as possibly breaking.
- No guarantee for experimental Go APIs. They are labeled experimental in the document for a reason.
Related pages
Get started
Give your first agent an identity.
Install the package, create an agent with scoped permissions, and read its first audit record. The core runs on Postgres, SQLite, MySQL or D1, and the Go module needs a single go get.
npm install @glinr/theauthgo get github.com/glincker/theauth-go