server/docs/api/sso.md

SSO API

The SSO API is used to link, unlink, and list external OpenID Connect providers that the user has linked their account to.

SSO Provider

interface SSOProvider {
    id: string;
    name: string;
    icon: string;
}

SSO Link

POST /api/v1/sso

Allows users to link their account to an external OpenID Connect provider.

• Returns: Link to redirect the user to the external provider.
• Authentication: Required
• Permissions: oauth
• Version History:
  • 0.6.0: Added.
  • 0.7.0: Permissions added.

Request

• issuer (string, required): The issuer ID of the OpenID Connect provider as set in config.

Example

POST /api/v1/sso
Authorization: Bearer ...
Content-Type: application/json

{
    "issuer": "google"
}

Response

200 OK

Link to redirect the user to the external provider's page.

{
    "link": "https://accounts.google.com/o/oauth2/auth?client_id=..."
}

SSO Unlink

DELETE /api/v1/sso/:issuer

Allows users to unlink their account from an external OpenID Connect provider.

• Returns: 204 No Content
• Authentication: Required
• Permissions: oauth
• Version History:
  • 0.6.0: Added.
  • 0.7.0: Permissions added.

Request

Example

DELETE /api/v1/sso/google
Authorization: Bearer ...

Response

204 No Content

Account successfully unlinked.

List Connected Providers

GET /api/v1/sso

Lists all external OpenID Connect providers that the user has linked their account to.

• Returns: Array of SSOProvider objects.
• Authentication: Required
• Permissions: oauth
• Version History:
  • 0.6.0: Added.
  • 0.7.0: Permissions added.

Request

Example

GET /api/v1/sso
Authorization: Bearer ...

Response

200 OK

Array of SSOProvider objects.

[
    {
        "id": "google",
        "name": "Google",
        "icon": "https://cdn.example.com/google.png"
    }
]

Get Linked Provider Data

GET /api/v1/sso/:issuer

Gets the data of an external OpenID Connect provider that the user has linked their account to.

• Returns: SSOProvider object.
• Authentication: Required
• Permissions: oauth
• Version History:
  • 0.6.0: Added.
  • 0.7.0: Permissions added.

Request

Example

GET /api/v1/sso/google
Authorization: Bearer ...

Response

200 OK

SSOProvider object.

{
    "id": "google",
    "name": "Google",
    "icon": "https://cdn.example.com/google.png"
}