Skip to documentation content
Raw .md
API & Developer Reference REST API Updated Oct 6, 2026

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:

Authorization: Bearer <access_token>
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:

curl -X GET "https://auth.ternis.net/.well-known/openid-configuration"

Response (200 OK):

{
  "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:

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):

{
  "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:

curl -X GET "https://auth.ternis.net/oauth/userinfo" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1Qi..." \
  -H "Accept: application/json"

Response (200 OK):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

[
  {
    "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:

{
  "name": "My Analytics Daemon",
  "redirect": "https://app.example.com/callback",
  "confidential": true
}

Response (201 Created):

{
  "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.


5.3. Update OAuth Client Settings

Updates the application name, authorized redirect URIs, or grant types while preserving the existing client ID and secret.

  • Method: PATCH or PUT
  • Path: /api/v1/oauth/clients/{client_id}
  • Auth: ****** (ternis:partner or account session)
  • Content-Type: application/json

Request Body:

{
  "name": "My Updated Analytics Daemon",
  "redirect": "https://app.example.com/new-callback,https://app.example.com/legacy-callback"
}

The secret is never returned by this endpoint. Use the separate regenerate-secret endpoint only when the secret itself must be replaced.


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:

curl -X GET "https://auth.ternis.net/api/domains"

Response (200 OK):

{
  "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"
  ]
}

7. Notifications & Email Platform

For exhaustive schemas, standard templates, code examples, and security tiers, see the dedicated Centralized Notifications & Email Platform Guide.

7.1. Available Endpoints Summary

Method Endpoint Required Scope Description
GET /api/v1/notifications/templates notifications:read Catalog of pre-configured notification templates
POST /api/v1/notifications/send-email email:send Send single notification / email (official apps only)
POST /api/v1/notifications/batch email:send Dispatch batch of up to 100 notifications
POST /api/v1/notifications/broadcast ternis:admin Ecosystem announcements broadcast by audience
GET /api/v1/user/notifications notifications:read Query user notifications feed with filtering
GET /api/v1/user/notifications/stats notifications:read Aggregate user inbox counts and category distribution
POST /api/v1/user/notifications/{id}/pin notifications:read Pin/unpin important alerts to top
POST /api/v1/user/notifications/{id}/archive notifications:read Archive/restore notification
PATCH /api/v1/user/notifications/{id}/read notifications:read Mark notification as read
POST /api/v1/user/notifications/read-all notifications:read Mark all notifications as read
POST /api/v1/user/notifications/clear-read notifications:read Permanently clear all read notifications
DELETE /api/v1/user/notifications/{id} notifications:read Delete notification
GET /api/v1/user/notifications/preferences notifications:read User channel settings & app permissions
PUT /api/v1/user/notifications/preferences notifications:read Update user notification preferences
POST /api/v1/user/apps/{clientId}/email-permission notifications:read Grant or revoke app email permission