# Ternis Auth & SSO Platform (llms.txt)
> Machine-readable summary for AI agents and LLMs integrating with Ternis Auth & Single Sign-On (SSO).

## Overview
Ternis Auth is a Laravel-powered OAuth 2.0 and OpenID Connect (OIDC) identity provider. It provides unified SSO across all Ternis digital properties and partner platforms.

- **Primary Base URL (Active)**: https://auth.ternis.net
- **Multi-Domain Network**:
  - `auth.ternis.net`: Global primary authentication server
  - `auth.ternis.org`: Ternis Foundation & community SSO
  - `auth.ternis.dev`: Developer sandbox & staging auth
  - `auth.t-api.de`: Dedicated API authentication gateway
  - `auth.thosted.de`: Cloud Services SSO gateway & allowed callback
  - `user.t-cdn.de` & `avatar.t-cdn.de`: Dedicated t-CDN cookieless user profile picture & avatar delivery
  - `user.t-api.de`: Dedicated user profile picture & avatar CDN
  - `account.ternis.org` / `account.ternis.net`: User account, memberships, and security portal
- **Identifier Strategy**: All entities (Users, Organizations, Memberships, Subscriptions, OAuth Clients) use RFC 4122 UUIDs (e.g. `550e8400-e29b-41d4-a716-446655440000`).

## User Classifications & Roles
Ternis Auth classifies users into 4 core tiers with specific claims and entitlements:
1. `ternis_member`: Core organization staff, maintainers, and community contributors with elevated internal access and badges.
2. `general_user`: Standard authenticated individuals in the ecosystem.
3. `paying_customer`: Customers with active billing plans, entitlements, and support tiers.
4. `partner`: Verified B2B partners, external developers, and integrators with OAuth client creation rights and elevated API quotas.

## Core Endpoints
- OpenID Connect Discovery: `https://auth.ternis.net/.well-known/openid-configuration`
- OAuth Server Metadata: `https://auth.ternis.net/.well-known/oauth-authorization-server`
- Authorize (Authorization Code + PKCE): `https://auth.ternis.net/oauth/authorize`
- Token Exchange: `POST https://auth.ternis.net/oauth/token`
- OIDC UserInfo: `GET https://auth.ternis.net/oauth/userinfo`
- User Profile Picture / Avatar: `GET https://auth.ternis.net/avatar/{identifier}` or `https://user.t-api.de/{user_id}.png` or `https://user.t-api.de/{username}.png` (supports .png, .svg, .jpg, .webp with automated initials and default silhouette fallback)
- User Profile API: `GET https://auth.ternis.net/api/v1/user`
- Organization Memberships: `GET https://auth.ternis.net/api/v1/memberships`
- Commercial Plans & Entitlements: `GET https://auth.ternis.net/api/plans` and `GET https://auth.ternis.net/api/v1/user/plan`
- Saved Addresses: `GET|POST https://auth.ternis.net/api/v1/user/addresses` and `PUT|DELETE https://auth.ternis.net/api/v1/user/addresses/{id}`
- Multi-Email & Verification: `GET|POST https://auth.ternis.net/api/v1/user/emails` and `POST https://auth.ternis.net/api/v1/user/emails/{id}/verify`
- Shared Ecosystem Balance & Wallet: `GET https://auth.ternis.net/api/v1/user/balance`, `POST https://auth.ternis.net/api/v1/user/balance/charge`, and `POST https://auth.ternis.net/api/v1/user/balance/topup`
- Partner OAuth Apps: `GET|POST https://auth.ternis.net/api/v1/oauth/clients`
- Domains & Ecosystem Status: `GET https://auth.ternis.net/api/domains`
- Interactive Docs: `https://auth.ternis.net/docs`
- Complete OpenAPI 3.1 Spec: `https://auth.ternis.net/api/openapi.json`
- Full LLM Documentation: `https://auth.ternis.net/llms-full.txt`
- Markdown API Manual: `https://auth.ternis.net/api/docs.md`

## OAuth 2.0 Scopes
- `openid`: Standard OpenID Connect identity assertion (sub claim)
- `profile`: Full name, avatar URL, username, and company
- `email`: Email address and verification status
- `ternis:sso`: Ecosystem-wide single sign-on cross-domain access
- `ternis:member`: Ternis core member organization affiliations and badges
- `ternis:customer`: Subscription plan tier, billing status, and feature flags
- `ternis:partner`: Partner tier, API quota limits, and webhook status
- `ternis:admin`: Administrative management operations

## Quick Integration (cURL)
```bash
# 1. Exchange authorization code for tokens
curl -X POST "https://auth.ternis.net/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_UUID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://your-app.com/callback",
    "code": "AUTHORIZATION_CODE"
  }'

# 2. Query OIDC UserInfo
curl -X GET "https://auth.ternis.net/oauth/userinfo" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```