--- title: Complete REST API Reference category: API & Developer Reference order: 9 badge: REST API description: Comprehensive endpoint reference with request parameters, schemas, authentication, and response examples. --- # Complete REST API Reference This document provides an exhaustive reference for all RESTful API endpoints exposed by the **Ternis Auth & SSO Platform**. All API endpoints return JSON with `Content-Type: application/json` unless otherwise specified. --- ## 1. Authentication & Headers Protected API endpoints require an OAuth 2.0 Bearer token in the `Authorization` request header: ```http Authorization: Bearer Accept: application/json ``` --- ## 2. Discovery Endpoints ### 2.1. OpenID Connect Discovery Returns OpenID Connect configuration and active endpoints. - **Method**: `GET` - **Path**: `/.well-known/openid-configuration` - **Auth**: None (Public) #### Request Example: ```bash curl -X GET "https://auth.ternis.net/.well-known/openid-configuration" ``` #### Response (200 OK): ```json { "issuer": "https://auth.ternis.net", "authorization_endpoint": "https://auth.ternis.net/oauth/authorize", "token_endpoint": "https://auth.ternis.net/oauth/token", "userinfo_endpoint": "https://auth.ternis.net/oauth/userinfo", "jwks_uri": "https://auth.ternis.net/oauth/jwks", "response_types_supported": ["code", "token"], "subject_types_supported": ["public"], "id_token_signing_alg_values_supported": ["RS256"], "scopes_supported": [ "openid", "profile", "email", "ternis:sso", "ternis:member", "ternis:customer", "ternis:partner", "ternis:admin" ], "token_endpoint_auth_methods_supported": [ "client_secret_basic", "client_secret_post", "none" ], "code_challenge_methods_supported": ["S256", "plain"] } ``` --- ## 3. OAuth 2.0 & Identity Endpoints ### 3.1. Issue Access Token Exchange an authorization code, refresh token, or client credentials for an access token. - **Method**: `POST` - **Path**: `/oauth/token` - **Auth**: Basic Auth or Form Parameters (`client_id` + `client_secret`) - **Content-Type**: `application/x-www-form-urlencoded` #### Parameters: | Parameter | Type | Required | Description | | :--- | :--- | :--- | :--- | | `grant_type` | string | Yes | `authorization_code`, `client_credentials`, or `refresh_token`. | | `client_id` | UUID | Yes | Client Application ID. | | `client_secret` | string | Conditional | Required for confidential backend clients. | | `code` | string | Conditional | Required for `authorization_code` grant. | | `code_verifier`| string | Conditional | Required if PKCE was used during authorization. | | `redirect_uri` | string | Conditional | Must match the URI sent during authorization. | | `refresh_token`| string | Conditional | Required for `refresh_token` grant. | #### Request Example: ```bash curl -X POST "https://auth.ternis.net/oauth/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=authorization_code" \ -d "client_id=9dc6e84a-714c-4e89-9a29-bc828cf99874" \ -d "client_secret=sec_abcdef1234567890" \ -d "redirect_uri=https://app.example.com/callback" \ -d "code=def50200..." \ -d "code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" ``` #### Response (200 OK): ```json { "token_type": "Bearer", "expires_in": 31536000, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...", "refresh_token": "def502008f1b6a378873ad82...", "id_token": "eyJhbGciOiJSUzI1NiIs..." } ``` --- ### 3.2. OpenID Connect UserInfo Retrieve identity claims for the authenticated user. - **Method**: `GET` - **Path**: `/oauth/userinfo` - **Auth**: Bearer Token (`openid` scope required) #### Request Example: ```bash curl -X GET "https://auth.ternis.net/oauth/userinfo" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1Qi..." \ -H "Accept: application/json" ``` #### Response (200 OK): ```json { "sub": "b2f6b897-4001-460d-8386-db93f1d8c1c4", "name": "Elena Rostova", "preferred_username": "elena.rostova", "email": "elena.rostova@ternis.org", "email_verified": true, "picture": "https://user.t-cdn.de/b2f6b897-4001-460d-8386-db93f1d8c1c4.png", "user_type": "ternis_member", "is_admin": false, "organization_ids": ["c8a7f920-5d61-41b3-a1f4-3d078be12884"] } ``` --- ## 4. User & Account APIs ### 4.1. Get Authenticated User Profile Returns detailed user profile, permissions, and status. - **Method**: `GET` - **Path**: `/api/v1/user` - **Auth**: Bearer Token #### Response (200 OK): ```json { "id": "b2f6b897-4001-460d-8386-db93f1d8c1c4", "name": "Elena Rostova", "username": "elena.rostova", "email": "elena.rostova@ternis.org", "user_type": "ternis_member", "is_admin": false, "avatar_url": "https://user.t-cdn.de/b2f6b897-4001-460d-8386-db93f1d8c1c4.png", "created_at": "2026-01-15T08:30:00Z" } ``` --- ### 4.2. Get User Organization Memberships Returns all teams and organizations the user belongs to. - **Method**: `GET` - **Path**: `/api/v1/memberships` - **Auth**: Bearer Token #### Response (200 OK): ```json { "user_id": "b2f6b897-4001-460d-8386-db93f1d8c1c4", "memberships": [ { "organization_id": "c8a7f920-5d61-41b3-a1f4-3d078be12884", "organization_name": "Ternis Core Platform", "slug": "ternis-core", "role": "admin" } ] } ``` --- ### 4.3. Upload / Update Avatar Upload an avatar image file or specify an external avatar URL. - **Method**: `POST` - **Path**: `/api/v1/user/avatar` - **Auth**: Bearer Token - **Content-Type**: `multipart/form-data` or `application/json` #### Parameters / Body: | Field | Type | Description | | :--- | :--- | :--- | | `avatar` | file | Image file (PNG, JPG, WebP, SVG, GIF up to 5MB). | | `avatar_url` | string | External image URL (e.g. `https://example.com/avatar.jpg`). | #### Response (200 OK): ```json { "success": true, "message": "Profile picture updated successfully.", "source": "upload", "avatar_url": "https://auth.ternis.net/storage/avatars/b2f6b897-4001-460d-8386-db93f1d8c1c4_1742000000.png", "user": { "id": "b2f6b897-4001-460d-8386-db93f1d8c1c4", "username": "elena.rostova", "avatar_url": "https://auth.ternis.net/storage/avatars/b2f6b897-4001-460d-8386-db93f1d8c1c4_1742000000.png", "has_custom_avatar": true } } ``` --- ### 4.4. Delete / Reset Avatar Reset custom avatar back to default auto-generated initials or platform silhouette. - **Method**: `DELETE` - **Path**: `/api/v1/user/avatar` - **Auth**: Bearer Token #### Response (200 OK): ```json { "success": true, "message": "Profile picture removed and reset to default.", "avatar_url": "https://auth.ternis.net/avatar/b2f6b897-4001-460d-8386-db93f1d8c1c4.png", "user": { "id": "b2f6b897-4001-460d-8386-db93f1d8c1c4", "username": "elena.rostova", "avatar_url": null, "avatar_path": null, "has_custom_avatar": false } } ``` --- ## 5. Developer & Partner APIs ### 5.1. List OAuth Clients Returns developer applications created by the user or partner. - **Method**: `GET` - **Path**: `/api/v1/oauth/clients` - **Auth**: Bearer Token (`ternis:partner` or account session) #### Response (200 OK): ```json [ { "id": "9dc6e84a-714c-4e89-9a29-bc828cf99874", "name": "Hosted Cloud Integration", "redirect_uris": [ "https://auth.thosted.de/callback", "https://app.thosted.de/sso/callback" ], "confidential": true, "revoked": false, "created_at": "2026-02-10T14:20:00Z" } ] ``` --- ### 5.2. Register New OAuth Client Programmatically creates a new OAuth client. - **Method**: `POST` - **Path**: `/api/v1/oauth/clients` - **Auth**: Bearer Token (`ternis:partner` or account session) - **Content-Type**: `application/json` #### Request Body: ```json { "name": "My Analytics Daemon", "redirect": "https://app.example.com/callback", "confidential": true } ``` #### Response (201 Created): ```json { "id": "9dc721a0-128f-4318-912b-31ca78198f12", "name": "My Analytics Daemon", "secret": "sec_89b2f34918e7c2a10d9f45...", "redirect": "https://app.example.com/callback", "confidential": true } ``` > [!CAUTION] > The `secret` parameter is **only returned once** upon creation. Store it in a secure secret manager immediately. --- ## 6. Ecosystem & Diagnostic APIs ### 6.1. Get Ecosystem Domains Configuration Returns the active domain context and all cluster mappings. - **Method**: `GET` - **Path**: `/api/domains` - **Auth**: None (Public) #### Request Example: ```bash curl -X GET "https://auth.ternis.net/api/domains" ``` #### Response (200 OK): ```json { "current": { "host": "auth.ternis.net", "type": "auth", "brand": "Ternis Auth (Global)", "portal_name": "Ternis Global Single Sign-On", "theme": "indigo", "tld": "net", "auth_url": "https://auth.ternis.net", "account_url": "https://account.ternis.net" }, "ecosystem_domains": { "auth.ternis.net": { "type": "auth", "tld": "net" }, "auth.ternis.org": { "type": "auth", "tld": "org" }, "auth.ternis.dev": { "type": "auth", "tld": "dev" }, "auth.t-api.de": { "type": "auth", "tld": "de" }, "auth.thosted.de": { "type": "auth", "tld": "de" }, "user.t-cdn.de": { "type": "user", "tld": "de" }, "avatar.t-cdn.de": { "type": "user", "tld": "de" }, "user.t-api.de": { "type": "user", "tld": "de" }, "account.ternis.org": { "type": "account", "tld": "org" } }, "allowed_redirect_patterns": [ "*.ternis.net", "*.ternis.org", "*.ternis.dev", "*.t-api.de", "*.t-cdn.de", "*.thosted.de", "localhost" ] } ```