--- title: Ternis Auth Developer & Agent API Reference category: Getting Started order: 1 badge: Overview description: Comprehensive guide and technical reference for the Ternis Auth & SSO multi-domain federation platform. --- # 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 | Domain | Role / Cluster | Purpose & Audience | | :--- | :--- | :--- | | **`auth.ternis.net`** | `auth` (Production) | Primary global OAuth 2.0 & OIDC authorization server and token authority. | | **`auth.ternis.org`** | `auth` (Foundation) | Community and open-source identity federation. | | **`auth.ternis.dev`** | `auth` (Developer) | Staging and sandbox environment for third-party developer integrations. | | **`auth.t-api.de`** | `auth` (API Edge) | Dedicated German infrastructure API gateway and SSO endpoint. | | **`auth.thosted.de`** | `auth` (Cloud SSO) | Cloud hosting & SaaS Single Sign-On authority and permitted callback hub. | | **`user.t-cdn.de`** | `user` (Media CDN) | Cookieless, ultra-fast profile picture delivery by UUID or username (`/{id}.png`). | | **`avatar.t-cdn.de`** | `user` (Media CDN) | Dedicated vector SVG and raster avatar delivery edge network. | | **`user.t-api.de`** | `user` (API CDN) | API profile picture resolution and avatar fallback endpoints. | | **`account.ternis.org`** | `account` (Portal) | Self-service user profile, credential security, and developer apps console. | --- ## 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 | Service | Endpoint | Method | Description | | :--- | :--- | :--- | :--- | | **OIDC Discovery** | `/.well-known/openid-configuration` | `GET` | OpenID Connect discovery metadata. | | **OAuth Metadata** | `/.well-known/oauth-authorization-server` | `GET` | RFC 8414 Authorization server metadata. | | **Authorize** | `/oauth/authorize` | `GET` | User authorization and consent screen. | | **Token Exchange** | `/oauth/token` | `POST` | Exchange auth code or credentials for access token. | | **OIDC UserInfo** | `/oauth/userinfo` | `GET` | OpenID Connect authenticated user claims. | | **User Profile API**| `/api/v1/user` | `GET` | Detailed user profile, tier, and memberships. | | **Memberships API** | `/api/v1/memberships` | `GET` | Organizations and team role affiliations. | | **Partner Apps** | `/api/v1/oauth/clients` | `GET/POST` | Programmatic OAuth client registration. | | **Avatar CDN** | `https://user.t-cdn.de/{identifier}.png` | `GET` | High-speed avatar delivery by UUID or handle. | | **Domain Status** | `/api/domains` | `GET` | Active cluster domains and redirect whitelist. | --- ## 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`