Ternis Auth Developer & Agent API Reference

Welcome to the Ternis Auth & SSO Platform developer reference. Ternis Auth is a high-performance, distributed identity provider and Single Sign-On (SSO) authority built on Laravel, implementing OAuth 2.0 (RFC 6749), PKCE (RFC 7636), and OpenID Connect 1.0 (OIDC) standards.

The platform provides unified user authentication, role-based authorization, enterprise subscription claims, partner developer tools, and an ultra-fast cookieless avatar media CDN across all properties in the Ternis network.

1. System Architecture #

Ternis Auth operates as a multi-domain federated identity fabric. Each domain serves a distinct functional role while sharing a unified relational datastore and token signature infrastructure:

                      +-----------------------------+
                      |       Ternis Account        |
                      |     account.ternis.org      |
                      |  (Profiles, Apps, Security) |
                      +--------------+--------------+
                                     |
    +--------------------------------+--------------------------------+
    |                                |                                |
+---+-------------------+  +---------+-----------+  +-----------------+---+
|  Primary Auth Edge    |  | Community & Fdn     |  | Hosted Services SSO |
|   auth.ternis.net     |  |   auth.ternis.org   |  |   auth.thosted.de   |
| (Global Production)   |  | (Open Source Hub)   |  |  (Cloud App Gateway)|
+-----------------------+  +---------------------+  +---------------------+
    |                                |                                |
+---+-------------------+  +---------+-----------+  +-----------------+---+
| Developer Sandbox     |  | Dedicated API Edge  |  | Cookieless Avatar   |
|   auth.ternis.dev     |  |   auth.t-api.de     |  |   user.t-cdn.de     |
| (Partner Integrations)|  | (German Gateway)    |  |  avatar.t-cdn.de    |
+-----------------------+  +---------------------+  +---------------------+

Domain Roles & Clustering #

2. Core Platform Principles #

1. Strict RFC 4122 Version 4 UUIDs #

Every entity in the system—including User, OAuthClient, Organization, Membership, CustomerSubscription, PartnerProfile, and SsoAuditLog—uses canonical 36-character RFC 4122 Version 4 UUIDs (e.g. b2f6b897-4001-460d-8386-db93f1d8c1c4). Numeric sequential IDs are strictly disallowed to prevent enumeration vulnerabilities.

2. Official vs. Unofficial App Transparency #

Applications created by Ternis Platform Administrators (is_admin: true) are verified as Official Platform Applications. All third-party or partner apps display a prominent security notice on the /oauth/authorize consent screen, disclosing developer details and verified domains.

3. Graceful Avatar Fallback Contract #

The media CDN (user.t-cdn.de, avatar.t-cdn.de, user.t-api.de) guarantees that standard image requests (GET /{user_id}.png or GET /{username}.png) never return HTTP 404 broken images. Missing or uninitialized avatars gracefully return an HTTP 200 response containing a beautiful neutral silhouette or color-coded initials.

4. Zero-Friction Single Sign-On (SSO) #

Users authenticated on any domain in the Ternis network can seamlessly authorize with other ecosystem services (*.ternis.net, *.ternis.org, *.thosted.de, *.t-api.de) without re-entering credentials.

3. Four User Classifications #

All accounts belong to one of four core tiers, controlling claim assertions and API entitlements:

1. Ternis Member (ternis_member):
   • Staff, core maintainers, and foundation contributors.
   • Entitled to ternis:member scope, internal GitHub org sync, and member badges.
2. General User (general_user):
   • Default tier for public users, consumers, and community members.
3. Paying Customer (paying_customer):
   • Subscribers with an active subscription (starter, pro, enterprise).
   • Grants ternis:customer scope, higher rate limits, and SLA support.
4. Verified Partner (partner):
   • Certified B2B developers and commercial integrations.
   • Grants ternis:partner scope, self-service confidential OAuth client creation, and webhooks.

4. Key Endpoints at a Glance #

5. Machine & AI Agent Integration #

Ternis Auth provides first-class discovery documents for autonomous coding agents, LLMs, and API clients:

• Compact LLM Context: GET /llms.txt and GET /.well-known/llms.txt
• Exhaustive LLM Manual: GET /llms-full.txt
• OpenAPI 3.1 Specification: GET /api/openapi.json
• Markdown Documentation: GET /docs/{slug}.md or GET /api/docs.md
• Interactive Documentation: GET /docs