{"openapi":"3.1.0","info":{"title":"Ternis Auth & SSO API","version":"1.0.0","description":"Multi-domain OAuth 2.0 and OpenID Connect (OIDC) Single Sign-On (SSO) platform powering the Ternis ecosystem (ternis.net, ternis.org, ternis.dev, auth.t-api.de, auth.thosted.de). Provides unified identity, role-based authorization, and user classification for Ternis Members, General Users, Paying Customers, and Partners.","contact":{"name":"Ternis Platform Engineering","url":"https:\/\/ternis.dev","email":"auth-support@ternis.net"},"license":{"name":"MIT","url":"https:\/\/opensource.org\/licenses\/MIT"}},"servers":[{"url":"https:\/\/auth.ternis.org","description":"Current active host (auth.ternis.org)"},{"url":"https:\/\/auth.ternis.net","description":"Primary Production Auth Network (.net)"},{"url":"https:\/\/auth.ternis.org","description":"Ternis Foundation Auth (.org)"},{"url":"https:\/\/auth.ternis.dev","description":"Ternis Developer Sandbox (.dev)"},{"url":"https:\/\/auth.t-api.de","description":"t-API Authentication Gateway (.de)"},{"url":"https:\/\/auth.thosted.de","description":"tHosted Single Sign-On Gateway (.de)"},{"url":"https:\/\/user.t-api.de","description":"t-API User Profile & Avatar CDN (.de)"},{"url":"https:\/\/user.t-cdn.de","description":"t-CDN User Profile & Avatar Edge (.de)"},{"url":"https:\/\/avatar.t-cdn.de","description":"t-CDN Avatar Edge Network (.de)"}],"tags":[{"name":"OAuth2 \/ OpenID Connect","description":"Standard RFC 6749, RFC 7636 (PKCE), and OpenID Connect endpoints"},{"name":"User Profile & Identity","description":"Authenticated user profile, classification, avatar, and metadata"},{"name":"Organizations & Memberships","description":"Ternis team memberships and organizational affiliations"},{"name":"Partner Developer Console","description":"OAuth client registration and partner integrations"},{"name":"Authorized Applications","description":"User OAuth client authorizations, token review, and access revocation"},{"name":"External OAuth & Identity Sync","description":"Synchronized identity providers (GitHub, Google, GitLab, Discord)"},{"name":"Address Book & Verification","description":"Multi-address storage and secondary email verification"},{"name":"Notifications & Email Delivery","description":"Transactional email sending and in-app notifications for official connected applications with explicit user consent"},{"name":"Ecosystem & Domains","description":"Multi-domain context and configuration discovery"}],"paths":{"\/.well-known\/openid-configuration":{"get":{"tags":["OAuth2 \/ OpenID Connect"],"summary":"OpenID Connect Discovery Document","description":"Returns standard OIDC discovery metadata pointing to active domain endpoints.","responses":{"200":{"description":"OpenID Connect Configuration JSON","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/OpenIdConfiguration"}}}}}}},"\/oauth\/authorize":{"get":{"tags":["OAuth2 \/ OpenID Connect"],"summary":"OAuth 2.0 Authorization Endpoint","description":"Initiate authorization code flow with PKCE or prompt user for consent.","parameters":[{"name":"response_type","in":"query","required":true,"schema":{"type":"string","example":"code"}},{"name":"client_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string","format":"uri"}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","example":"openid profile email ternis:sso"}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"code_challenge","in":"query","required":false,"schema":{"type":"string"}},{"name":"code_challenge_method","in":"query","required":false,"schema":{"type":"string","example":"S256"}}],"responses":{"302":{"description":"Redirect to login or authorization redirect URI"},"200":{"description":"Render authorization consent dialog"}}}},"\/oauth\/token":{"post":{"tags":["OAuth2 \/ OpenID Connect"],"summary":"OAuth 2.0 Token Exchange Endpoint","description":"Exchange authorization code, client credentials, or refresh token for Bearer access token.","requestBody":{"required":true,"content":{"application\/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","client_id"],"properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token","client_credentials"]},"client_id":{"type":"string","format":"uuid"},"client_secret":{"type":"string"},"redirect_uri":{"type":"string"},"code":{"type":"string"},"code_verifier":{"type":"string"},"refresh_token":{"type":"string"},"scope":{"type":"string"}}}}}},"responses":{"200":{"description":"Token exchange successful","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TokenResponse"}}}},"401":{"description":"Invalid client credentials or code"}}}},"\/oauth\/userinfo":{"get":{"tags":["OAuth2 \/ OpenID Connect"],"summary":"OIDC UserInfo Endpoint","description":"Returns claims about the authenticated user based on granted scopes.","security":[{"OAuth2Bearer":[]}],"responses":{"200":{"description":"Standard OpenID Connect Claims","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/OidcClaims"}}}},"401":{"description":"Unauthenticated"}}}},"\/api\/v1\/user":{"get":{"tags":["User Profile & Identity"],"summary":"Get Detailed User Profile","description":"Returns comprehensive identity details including Ternis membership badges, role, partner status, and subscription tier.","security":[{"OAuth2Bearer":[]}],"responses":{"200":{"description":"User profile object","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/UserProfile"}}}}}}},"\/api\/v1\/memberships":{"get":{"tags":["Organizations & Memberships"],"summary":"List User Memberships","description":"Lists the Ternis organizations and teams that the user is a member of.","security":[{"OAuth2Bearer":[]}],"responses":{"200":{"description":"List of memberships"}}}},"\/api\/v1\/oauth\/clients":{"get":{"tags":["Partner Developer Console"],"summary":"List Registered OAuth Clients","security":[{"OAuth2Bearer":[]}],"responses":{"200":{"description":"List of developer OAuth clients"}}},"post":{"tags":["Partner Developer Console"],"summary":"Register New OAuth Client Application","security":[{"OAuth2Bearer":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["name","redirect"],"properties":{"name":{"type":"string","example":"Ternis Analytics Dashboard"},"redirect":{"type":"string","example":"https:\/\/app.ternis.dev\/callback"},"confidential":{"type":"boolean","default":true},"grant_types":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"OAuth Client created"}}}},"\/api\/domains":{"get":{"tags":["Ecosystem & Domains"],"summary":"Get Ecosystem Domains & Configuration","description":"Returns active domain metadata, cluster mappings (auth.ternis.net, auth.ternis.org, auth.ternis.dev, auth.t-api.de, auth.thosted.de, user.t-api.de, user.t-cdn.de, avatar.t-cdn.de, account.ternis.org), and redirect policy.","responses":{"200":{"description":"Domain ecosystem configuration"}}}},"\/avatar\/{identifier}":{"get":{"tags":["User Profile & Identity"],"summary":"Get User Profile Picture \/ Avatar","description":"Returns user avatar image by UUID, username, or email. Supports PNG, SVG, JPG, WebP formats with automated initials and default silhouette fallback.","parameters":[{"name":"identifier","in":"path","required":true,"description":"UUID, username, or email with optional .png, .svg extension","schema":{"type":"string"}},{"name":"size","in":"query","required":false,"description":"Image dimensions in pixels (16 to 1024, default 256)","schema":{"type":"integer","default":256}},{"name":"fallback","in":"query","required":false,"description":"Fallback style: default, silhouette, initials, 404","schema":{"type":"string","default":"default"}}],"responses":{"200":{"description":"Avatar image stream","content":{"image\/png":{"schema":{"type":"string","format":"binary"}},"image\/svg+xml":{"schema":{"type":"string"}}}}}}},"\/api\/v1\/user\/oauth-accounts":{"get":{"tags":["External OAuth & Identity Sync"],"summary":"List Synced External OAuth Accounts","description":"Returns list of synced external accounts (e.g. GitHub, Google) linked to the user.","security":[{"OAuth2Bearer":[]}],"responses":{"200":{"description":"List of synced OAuth accounts","content":{"application\/json":{"schema":{"type":"object","properties":{"oauth_accounts":{"type":"array","items":{"$ref":"#\/components\/schemas\/OAuthProviderAccount"}}}}}}}}}},"\/api\/v1\/user\/oauth-accounts\/{provider}\/sync":{"post":{"tags":["External OAuth & Identity Sync"],"summary":"Re-sync External OAuth Provider Account","description":"Forces a background profile re-sync with the external provider (e.g. GitHub).","security":[{"OAuth2Bearer":[]}],"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","enum":["github","google","gitlab","discord"]}}],"responses":{"200":{"description":"Account synced successfully"},"404":{"description":"Linked account not found"}}}},"\/api\/v1\/user\/oauth-accounts\/{provider}":{"delete":{"tags":["External OAuth & Identity Sync"],"summary":"Disconnect External OAuth Account","description":"Unlinks the external provider account from the user identity.","security":[{"OAuth2Bearer":[]}],"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Account disconnected"},"404":{"description":"Account not found"}}}},"\/api\/v1\/user\/avatar":{"post":{"tags":["User Profile & Identity"],"summary":"Upload or Update User Profile Picture","description":"Upload an image file (PNG, JPG, WebP, SVG, GIF up to 5MB) or supply an external avatar URL.","security":[{"OAuth2Bearer":[]}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","properties":{"avatar":{"type":"string","format":"binary"},"avatar_url":{"type":"string","format":"uri"}}}},"application\/json":{"schema":{"type":"object","properties":{"avatar_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Avatar updated successfully"},"422":{"description":"Validation error"}}},"delete":{"tags":["User Profile & Identity"],"summary":"Remove Custom Avatar and Reset to Initials","security":[{"OAuth2Bearer":[]}],"responses":{"200":{"description":"Avatar reset to default initials\/silhouette"}}}},"\/api\/v1\/user\/addresses":{"get":{"tags":["Address Book & Verification"],"summary":"List User Addresses","description":"Returns all saved postal addresses with formatted strings and standard OIDC address claim payloads.","security":[{"OAuth2Bearer":[]}],"responses":{"200":{"description":"List of user addresses","content":{"application\/json":{"schema":{"type":"object","properties":{"addresses":{"type":"array","items":{"$ref":"#\/components\/schemas\/UserAddress"}}}}}}}}},"post":{"tags":["Address Book & Verification"],"summary":"Create New User Address","security":[{"OAuth2Bearer":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["street","postal_code","city","country_code"],"properties":{"type":{"type":"string","enum":["billing","shipping","legal","office","home"]},"label":{"type":"string"},"recipient_name":{"type":"string"},"company_name":{"type":"string"},"street":{"type":"string"},"street_line_2":{"type":"string"},"postal_code":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country_code":{"type":"string","example":"DE"},"is_primary":{"type":"boolean"},"is_billing":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Address created"},"422":{"description":"Validation error"}}}},"\/api\/v1\/user\/addresses\/{id}":{"put":{"tags":["Address Book & Verification"],"summary":"Update Address","security":[{"OAuth2Bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Address updated"},"404":{"description":"Address not found"}}},"delete":{"tags":["Address Book & Verification"],"summary":"Delete Address","security":[{"OAuth2Bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Address deleted"},"404":{"description":"Address not found"}}}},"\/api\/v1\/user\/emails":{"get":{"tags":["Address Book & Verification"],"summary":"List User Emails & Verification Status","security":[{"OAuth2Bearer":[]}],"responses":{"200":{"description":"Primary and secondary emails list","content":{"application\/json":{"schema":{"type":"object","properties":{"primary_email":{"$ref":"#\/components\/schemas\/UserEmail"},"emails":{"type":"array","items":{"$ref":"#\/components\/schemas\/UserEmail"}}}}}}}}},"post":{"tags":["Address Book & Verification"],"summary":"Add Secondary Email to Account","security":[{"OAuth2Bearer":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"Email added, verification token issued"},"422":{"description":"Validation error"}}}},"\/api\/v1\/user\/emails\/{id}\/verify":{"post":{"tags":["Address Book & Verification"],"summary":"Verify User Email Address","security":[{"OAuth2Bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"UUID or \"primary\"","schema":{"type":"string"}}],"responses":{"200":{"description":"Email verified"}}}},"\/api\/v1\/user\/emails\/{id}":{"delete":{"tags":["Address Book & Verification"],"summary":"Remove Secondary Email","security":[{"OAuth2Bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Email removed"}}}},"\/api\/v1\/user\/domains":{"get":{"tags":["Custom Domains & Verification"],"summary":"List User Verified and Pending Custom Domains","description":"Returns list of all domains registered by the user with DNS TXT challenge instructions and verification status.","security":[{"OAuth2Bearer":["ternis:domains","domains:read","domains:write"]}],"responses":{"200":{"description":"List of user domains"}}},"post":{"tags":["Custom Domains & Verification"],"summary":"Register a New Custom Domain","description":"Register domain to begin DNS TXT or HTTP well-known verification challenge.","security":[{"OAuth2Bearer":["domains:write"]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"example.com"},"verification_method":{"type":"string","enum":["dns_txt","http_well_known"],"default":"dns_txt"}}}}}},"responses":{"201":{"description":"Domain registered for verification"},"403":{"description":"Missing domains:write scope"},"409":{"description":"Domain already verified by another account"},"422":{"description":"Invalid domain format"}}}},"\/api\/v1\/user\/domains\/{id}\/verify":{"post":{"tags":["Custom Domains & Verification"],"summary":"Trigger Domain DNS Verification Check","security":[{"OAuth2Bearer":["domains:write","domains:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Domain successfully verified"},"403":{"description":"Missing domains:write or domains:read scope"},"422":{"description":"Verification check failed"}}}},"\/api\/v1\/user\/domains\/{id}":{"delete":{"tags":["Custom Domains & Verification"],"summary":"Remove Custom Domain","security":[{"OAuth2Bearer":["domains:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Domain removed from account"},"403":{"description":"Missing domains:write scope"}}}},"\/api\/v1\/user\/authorized-apps":{"get":{"tags":["Authorized Applications"],"summary":"List Applications Authorized by User","description":"Returns list of third-party and ecosystem apps currently holding active OAuth tokens for the user.","security":[{"OAuth2Bearer":[]}],"responses":{"200":{"description":"List of authorized applications","content":{"application\/json":{"schema":{"type":"object","properties":{"authorized_applications":{"type":"array","items":{"type":"object","properties":{"client_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"redirect_uris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"first_authorized_at":{"type":"string","format":"date-time"},"last_active_at":{"type":"string","format":"date-time"}}}}}}}}}}}},"\/api\/v1\/user\/authorized-apps\/{clientId}":{"delete":{"tags":["Authorized Applications"],"summary":"Revoke Application Access","description":"Revokes all active OAuth tokens and refresh tokens for the given application.","security":[{"OAuth2Bearer":[]}],"parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Access revoked"},"404":{"description":"No active tokens found for application"}}}},"\/api\/v1\/user\/notifications\/send-email":{"post":{"tags":["Notifications & Email Delivery"],"summary":"Send Email & In-App Notification to User","description":"Dispatches an email and in-app notification from an official application. Requires [email:send] scope and explicit user permission.","security":[{"OAuth2Bearer":["email:send"]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["subject","message"],"properties":{"subject":{"type":"string","maxLength":255,"example":"Your deployment completed"},"message":{"type":"string","example":"Your service deployment is live."},"action_url":{"type":"string","format":"uri","example":"https:\/\/ternis.link\/status"},"action_text":{"type":"string","example":"View Status"},"category":{"type":"string","enum":["app","security","transactional","billing","alert"],"default":"app"},"priority":{"type":"string","enum":["low","normal","high","urgent"],"default":"normal"},"in_app_only":{"type":"boolean","default":false},"client_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Email and notification sent successfully"},"403":{"description":"Forbidden: client is unofficial, missing email:send scope, or user did not grant permission"},"422":{"description":"Validation error"}}}},"\/api\/v1\/user\/notifications":{"get":{"tags":["Notifications & Email Delivery"],"summary":"List User In-App Notifications","description":"Returns recent in-app notifications and unread counts.","security":[{"OAuth2Bearer":["notifications:read"]}],"parameters":[{"name":"unread_only","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Notifications retrieved successfully"}}}},"\/api\/v1\/user\/notifications\/preferences":{"get":{"tags":["Notifications & Email Delivery"],"summary":"Get Notification & Email Preferences","security":[{"OAuth2Bearer":[]}],"responses":{"200":{"description":"Preferences and app permissions returned"}}},"put":{"tags":["Notifications & Email Delivery"],"summary":"Update Notification Preferences","security":[{"OAuth2Bearer":[]}],"responses":{"200":{"description":"Preferences updated"}}}},"\/api\/v1\/user\/apps\/{clientId}\/email-permission":{"post":{"tags":["Notifications & Email Delivery"],"summary":"Grant or Revoke App Email Sending Permission","security":[{"OAuth2Bearer":[]}],"parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["allow"],"properties":{"allow":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Permission updated"}}}}},"components":{"securitySchemes":{"OAuth2Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Access token obtained from \/oauth\/token"}},"schemas":{"OpenIdConfiguration":{"type":"object","properties":{"issuer":{"type":"string","format":"uri"},"authorization_endpoint":{"type":"string","format":"uri"},"token_endpoint":{"type":"string","format":"uri"},"userinfo_endpoint":{"type":"string","format":"uri"},"jwks_uri":{"type":"string","format":"uri"},"scopes_supported":{"type":"array","items":{"type":"string"}},"response_types_supported":{"type":"array","items":{"type":"string"}},"grant_types_supported":{"type":"array","items":{"type":"string"}}}},"TokenResponse":{"type":"object","properties":{"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"integer","example":1296000},"access_token":{"type":"string"},"refresh_token":{"type":"string"},"scope":{"type":"string"}}},"OidcClaims":{"type":"object","properties":{"sub":{"type":"string","format":"uuid"},"name":{"type":"string"},"preferred_username":{"type":"string"},"email":{"type":"string","format":"email"},"email_verified":{"type":"boolean"},"picture":{"type":"string","format":"uri"},"user_type":{"type":"string","enum":["ternis_member","general_user","paying_customer","partner"]},"role":{"type":"string","enum":["superadmin","admin","developer","member","billing_manager","user"]},"ternis_member":{"type":"object","properties":{"is_member":{"type":"boolean"},"member_badge":{"type":"string"},"organizations":{"type":"object"}}},"ternis_customer":{"type":"object","properties":{"is_paying":{"type":"boolean"},"status":{"type":"string"}}},"ternis_partner":{"type":"object","properties":{"is_partner":{"type":"boolean"},"company_name":{"type":"string"},"tier":{"type":"string"},"verified":{"type":"boolean"}}}}},"UserProfile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"username":{"type":"string"},"email":{"type":"string","format":"email"},"email_verified":{"type":"boolean"},"user_type":{"type":"string"},"role":{"type":"string"},"status":{"type":"string"},"avatar_url":{"type":"string","format":"uri"},"is_ternis_member":{"type":"boolean"},"is_partner":{"type":"boolean"},"is_paying_customer":{"type":"boolean"}}},"OAuthProviderAccount":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string","example":"github"},"provider_name":{"type":"string","example":"GitHub"},"provider_user_id":{"type":"string","example":"12345678"},"username":{"type":"string","example":"octocat"},"email":{"type":"string","format":"email","example":"octocat@github.com"},"avatar_url":{"type":"string","format":"uri"},"profile_url":{"type":"string","format":"uri"},"scopes":{"type":"array","items":{"type":"string"}},"synced_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"AuthorizedApplication":{"type":"object","properties":{"client_id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"ternis.link"},"redirect_uris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"first_authorized_at":{"type":"string","format":"date-time"},"last_active_at":{"type":"string","format":"date-time"}}},"UserAddress":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["billing","shipping","legal","office","home"]},"label":{"type":"string"},"recipient_name":{"type":"string"},"company_name":{"type":"string"},"street":{"type":"string"},"street_line_2":{"type":"string"},"postal_code":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country_code":{"type":"string","example":"DE"},"is_primary":{"type":"boolean"},"is_billing":{"type":"boolean"},"formatted":{"type":"string"},"oidc_claim":{"type":"object"}}},"UserEmail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"is_primary":{"type":"boolean"},"is_verified":{"type":"boolean"},"verified_at":{"type":"string","format":"date-time"}}}}}}