Versia Server Docs

Appearance

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 ​

ts
interface SSOProvider {
    id: string;
    name: string;
    icon: string;
}
http
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 ​

http
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.

json
{
    "link": "https://accounts.google.com/o/oauth2/auth?client_id=..."
}
http
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 ​

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

Response ​

204 No Content ​

Account successfully unlinked.

List Connected Providers ​

http
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 ​

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

Response ​

200 OK ​

Array of SSOProvider objects.

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

Get Linked Provider Data ​

http
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 ​

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

Response ​

200 OK ​

SSOProvider object.

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