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.

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

Complete REST API Reference

1. Authentication & Headers #

2. Discovery Endpoints #

2.1. OpenID Connect Discovery #

Request Example:

Response (200 OK):

3. OAuth 2.0 & Identity Endpoints #

3.1. Issue Access Token #

Parameters:

Request Example:

Response (200 OK):

3.2. OpenID Connect UserInfo #

Request Example:

Response (200 OK):

4. User & Account APIs #

4.1. Get Authenticated User Profile #

Response (200 OK):

4.2. Get User Organization Memberships #

Response (200 OK):

4.3. Upload / Update Avatar #

Parameters / Body:

Response (200 OK):

4.4. Delete / Reset Avatar #

Response (200 OK):

5. Developer & Partner APIs #

5.1. List OAuth Clients #

Response (200 OK):

5.2. Register New OAuth Client #

Request Body:

Response (201 Created):

6. Ecosystem & Diagnostic APIs #

6.1. Get Ecosystem Domains Configuration #

Request Example:

Response (200 OK):

1. Authentication & Headers

2. Discovery Endpoints

2.1. OpenID Connect Discovery

3. OAuth 2.0 & Identity Endpoints

3.1. Issue Access Token

3.2. OpenID Connect UserInfo

4. User & Account APIs

4.1. Get Authenticated User Profile

4.2. Get User Organization Memberships

4.3. Upload / Update Avatar

4.4. Delete / Reset Avatar

5. Developer & Partner APIs

5.1. List OAuth Clients

5.2. Register New OAuth Client

6. Ecosystem & Diagnostic APIs

6.1. Get Ecosystem Domains Configuration