Connections (SSO)

Connections let your users sign in with external identity providers like Google, GitHub, or any OIDC-compatible service. Each connection is configured per environment and uses the OAuth2/OIDC protocol under the hood.

Supported Providers

Provider	Strategy	Discovery URL
Google	`google`	Not required
Microsoft (Azure AD)	`microsoft`	Not required
GitHub	`github`	Not required
Facebook	`facebook`	Not required
Discord	`discord`	Not required
GitLab	`gitlab`	Optional (for self-hosted)
Slack	`slack`	Not required
LinkedIn	`linkedin`	Not required
Bitbucket	`bitbucket`	Not required
Auth0	`auth0`	Required
Generic OIDC	`oidc`	Required

The Generic OIDC strategy works with any OpenID Connect provider. Provide the discovery URL (e.g. https://idp.example.com/.well-known/openid-configuration) and Paylent handles the rest.

How It Works

Your user clicks “Sign in with Google” (or another provider) on the login page
Paylent redirects them to the provider’s authorization endpoint
The user authenticates with the provider
The provider redirects back to Paylent with an authorization code
Paylent exchanges the code for user profile information
If the user already exists (matched by email), they are signed in. If not, a new account is created (when registration is enabled)

Provider credentials (client ID and secret) are encrypted at rest.

Creating a Connection

Via the Dashboard

Navigate to Connections in the sidebar. Click Add Connection, select a provider, and enter your OAuth credentials. Each provider’s setup form includes instructions for obtaining the client ID and secret from the provider’s developer console.

Via the Management API

curl -X POST https://acme-test.paylent.com/api/connections \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "connection",
      "attributes": {
        "strategy": "google",
        "display_name": "Google",
        "client_id": "YOUR_GOOGLE_CLIENT_ID",
        "client_secret": "YOUR_GOOGLE_CLIENT_SECRET",
        "scopes": "openid email profile"
      }
    }
  }'

For providers that require a discovery URL (OIDC, Auth0):

curl -X POST https://acme-test.paylent.com/api/connections \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "connection",
      "attributes": {
        "strategy": "oidc",
        "display_name": "Corporate SSO",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "discovery_url": "https://idp.example.com/.well-known/openid-configuration",
        "scopes": "openid email profile"
      }
    }
  }'

Configuration Options

Field	Required	Default	Description
`strategy`	Yes	—	One of the supported provider strategies
`display_name`	Yes	—	Label shown on the login page
`client_id`	Yes	—	OAuth client ID from the provider
`client_secret`	Yes	—	OAuth client secret from the provider
`discovery_url`	Depends	—	Required for `oidc` and `auth0`; optional for `gitlab`
`scopes`	Yes	`openid email profile`	Space-separated OAuth scopes to request
`enabled`	No	`true`	Set to `false` to disable without deleting
`enforce_sso`	No	`false`	When `true`, forces users to sign in via this provider

Organization-Scoped Connections

Connections can be scoped to a specific organization. This is useful for enterprise customers who need their own SSO provider while other users in the same environment use a different login method.

curl -X POST https://acme-test.paylent.com/api/connections \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "connection",
      "attributes": {
        "strategy": "oidc",
        "display_name": "Acme Corp SSO",
        "client_id": "...",
        "client_secret": "...",
        "discovery_url": "https://login.acmecorp.com/.well-known/openid-configuration"
      },
      "relationships": {
        "organization": {
          "data": { "type": "organization", "id": "ORGANIZATION_ID" }
        }
      }
    }
  }'

Environment-level connections (no organization) are available to all users. Organization-scoped connections are only shown to members of that organization.

Redirect URI

When configuring your OAuth app with the provider, use this callback URL:

https://{environment-handle}.paylent.com/auth/sso/callback

For example: https://acme-test.paylent.com/auth/sso/callback

User Matching

When a user signs in through an SSO connection:

Existing user (by email): The provider identity is linked to the existing account and the user is signed in
New user (registration enabled): A new account is created with the profile information from the provider (email, name) and the user is signed in
New user (registration disabled): The login is rejected with an error

Each user can have one linked provider identity. If a user already has a different provider linked, they cannot link a second one through SSO — they must sign in with their existing method.

SSO Endpoints

Endpoint	Description
`GET /auth/sso/:connection_id`	Initiates SSO login — redirects to the provider
`GET /auth/sso/callback`	Handles the provider’s callback after authentication

These endpoints are used automatically by the hosted login page. If you’re building a custom login UI, redirect users to /auth/sso/:connection_id to start the SSO flow.