Social providers and email templates

Configure application social sign-in and workspace email content. Social-provider credentials come from the provider developer console; provider callback routes are browser flows.

API conventions · All endpoints · Schemas

`/e/v1/developer/templates/`

Manage workspace email templates.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_templates.

Optional list filters workspace_id and oauth_client where shown below; detail routes check resource ownership.

Request / response schema: EmailTemplate.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`oauth_client`	`not supplied`
query	`workspace_id`	`not supplied`

Related schemas: EmailTemplate.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "reset_password",
    "subject": "EXAMPLE_SUBJECT",
    "body": "EXAMPLE_BODY",
    "html_content": "EXAMPLE_HTML_CONTENT",
    "created_at": "2026-10-26T12:00:00Z",
    "updated_at": "2026-10-26T12:00:00Z",
    "is_default": true,
    "created_via_api_key": "EXAMPLE_CREATED_VIA_API_KEY",
    "developer_id": "EXAMPLE_DEVELOPER_ID",
    "workspace": "11111111-1111-4111-8111-111111111111"
  }
]

403 — json

{
  "error": "Workspace not found or access denied"
}

404 — json

{
  "error": "Workspace not found"
}

POST

Required developer-token scope: write_templates.

Supply workspace explicitly and the required fields in the linked schema. Plan features, quotas and resource ownership apply. body and html_content are aliases; conflicting values are rejected. Template names are unique per workspace; duplicates can return 409.

Request / response schema: EmailTemplate.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`user_plan_id`	`not supplied`
body	`workspace`	`not supplied`
query	`workspace_id`	`not supplied`

Related schemas: EmailTemplate.

Example request body:

{
  "name": "email_verification",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "subject": "Verify your email",
  "body": "Your code is {{ verification_code }}"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

201 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "reset_password",
  "subject": "EXAMPLE_SUBJECT",
  "body": "EXAMPLE_BODY",
  "html_content": "EXAMPLE_HTML_CONTENT",
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "is_default": true,
  "created_via_api_key": "EXAMPLE_CREATED_VIA_API_KEY",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111"
}

400 — json

{
  "error": "EXAMPLE: EXAMPLE"
}

400 — json

{
  "error": "workspace_id parameter is required"
}

403 — json

{
  "error": "You do not have access to this workspace"
}

404 — json

{
  "error": "Workspace not found"
}

409 — json

{
  "error": "A template with the name 'EXAMPLE' already exists for this application."
}

500 — json

{
  "error": "An unexpected error occurred: EXAMPLE"
}

`/e/v1/developer/templates/{template_id}/`

Manage workspace email templates.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_templates.

Optional list filters workspace_id and oauth_client where shown below; detail routes check resource ownership.

Path parameters: template_id (uuid, required).

Request / response schema: EmailTemplate.

Related schemas: EmailTemplate.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "reset_password",
  "subject": "EXAMPLE_SUBJECT",
  "body": "EXAMPLE_BODY",
  "html_content": "EXAMPLE_HTML_CONTENT",
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "is_default": true,
  "created_via_api_key": "EXAMPLE_CREATED_VIA_API_KEY",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111"
}

PATCH

Required developer-token scope: write_templates.

Partial update using the linked serializer. Detail ownership applies. Default email templates cannot be edited.

Path parameters: template_id (uuid, required).

Request / response schema: EmailTemplate.

Related schemas: EmailTemplate.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "reset_password",
  "subject": "EXAMPLE_SUBJECT",
  "body": "EXAMPLE_BODY",
  "html_content": "EXAMPLE_HTML_CONTENT",
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "is_default": true,
  "created_via_api_key": "EXAMPLE_CREATED_VIA_API_KEY",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111"
}

400 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

400 — json

{
  "error": "Default templates cannot be modified"
}

DELETE

Required developer-token scope: write_templates.

No body; detail ownership applies. Default email templates cannot be deleted.

Path parameters: template_id (uuid, required).

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

204 — json

No response body.

400 — json

{
  "error": "Default templates cannot be deleted"
}

`/e/v1/oauth/google/`

Start Google social authentication.

Query includes oauth_client/client context and optional OAuth redirect/state/PKCE parameters listed below. Requires a configured, active provider for the selected client/workspace. Returns a provider redirect, not JSON.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`client_id`	`not supplied`
query	`redirect_uri`	`not supplied`
query	`state`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

302 — redirect

Redirect: inspect Location and preserve cookies.

400 — json

{
  "error": "Missing client_id parameter"
}

400 — json

{
  "error": "Invalid client ID"
}

400 — json

{
  "error": "Google login not configured for this client"
}

500 — json

{
  "error": "Error processing request"
}

500 — json

{
  "error": "Google OAuth not properly configured"
}

500 — json

{
  "error": "Error initiating Google login: EXAMPLE"
}

500 — json

{
  "error": "Error building callback URL"
}

`/e/v1/oauth/google/callback/`

Complete Google social authentication.

GET

Provider supplies authorization code and state (or error). Preserve the original browser session/state; do not call this endpoint with a fabricated code. Returns a hosted-login/consent/application redirect or provider-specific error.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`code`	`not supplied`
query	`state`	`not supplied`
query	`error`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

302 — redirect

Redirect: inspect Location and preserve cookies.

400 — json

{
  "error": "Google authentication failed: EXAMPLE"
}

400 — json

{
  "error": "Invalid state parameter"
}

400 — json

{
  "error": "Missing redirection information"
}

400 — json

{
  "error": "Email not provided by Google"
}

500 — json

{
  "error": "Error processing Google authentication: EXAMPLE"
}

500 — json

{
  "error": "Failed to create user in external database"
}

`/e/v1/oauth/github/`

Start GitHub social authentication.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`client_id`	`not supplied`
query	`redirect_uri`	`not supplied`
query	`state`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

302 — redirect

Redirect: inspect Location and preserve cookies.

400 — json

{
  "error": "Missing client_id parameter"
}

400 — json

{
  "error": "Invalid client ID"
}

400 — json

{
  "error": "GitHub login not configured for this client"
}

500 — json

{
  "error": "Error processing request"
}

500 — json

{
  "error": "GitHub OAuth not properly configured"
}

500 — json

{
  "error": "Error initiating GitHub login: EXAMPLE"
}

`/e/v1/oauth/github/callback/`

Complete GitHub social authentication.

GET

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`code`	`not supplied`
query	`state`	`not supplied`
query	`error`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

302 — redirect

Redirect: inspect Location and preserve cookies.

400 — json

{
  "error": "GitHub authentication failed: EXAMPLE"
}

400 — json

{
  "error": "Invalid state parameter"
}

400 — json

{
  "error": "Missing redirection information"
}

400 — json

{
  "error": "Email not provided by GitHub. Please make your email public in GitHub settings."
}

500 — json

{
  "error": "Error processing GitHub authentication: EXAMPLE"
}

500 — json

{
  "error": "Failed to create user in external database"
}

`/e/v1/oauth/linkedin/`

Start LinkedIn social authentication.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`client_id`	`not supplied`
query	`redirect_uri`	`not supplied`
query	`state`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

302 — redirect

Redirect: inspect Location and preserve cookies.

400 — json

{
  "error": "Missing client_id parameter"
}

400 — json

{
  "error": "Invalid client ID"
}

400 — json

{
  "error": "LinkedIn login not configured for this client"
}

500 — json

{
  "error": "Error processing request"
}

500 — json

{
  "error": "LinkedIn OAuth not properly configured"
}

500 — json

{
  "error": "Error initiating LinkedIn login: EXAMPLE"
}

`/e/v1/oauth/linkedin/callback/`

Complete LinkedIn social authentication.

GET

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`code`	`not supplied`
query	`state`	`not supplied`
query	`error`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

302 — redirect

Redirect: inspect Location and preserve cookies.

400 — json

{
  "error": "LinkedIn authentication failed: EXAMPLE"
}

400 — json

{
  "error": "Invalid state parameter"
}

400 — json

{
  "error": "Missing redirection information"
}

400 — json

{
  "error": "Email not provided by LinkedIn"
}

500 — json

{
  "error": "Error processing LinkedIn authentication: EXAMPLE"
}

500 — json

{
  "error": "Failed to create user in external database"
}

`/e/v1/oauth/facebook/`

Start Facebook social authentication.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`client_id`	`not supplied`
query	`redirect_uri`	`not supplied`
query	`state`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

302 — redirect

Redirect: inspect Location and preserve cookies.

400 — json

{
  "error": "Missing client_id parameter"
}

400 — json

{
  "error": "Invalid client ID"
}

400 — json

{
  "error": "Facebook login not configured for this client"
}

500 — json

{
  "error": "Error processing request"
}

500 — json

{
  "error": "Facebook OAuth not properly configured"
}

500 — json

{
  "error": "Error initiating Facebook login: EXAMPLE"
}

`/e/v1/oauth/facebook/callback/`

Complete Facebook social authentication.

GET

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`code`	`not supplied`
query	`state`	`not supplied`
query	`error`	`not supplied`

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

302 — redirect

Redirect: inspect Location and preserve cookies.

400 — json

{
  "error": "Facebook authentication failed: EXAMPLE"
}

400 — json

{
  "error": "Invalid state parameter"
}

400 — json

{
  "error": "Missing redirection information"
}

400 — json

{
  "error": "Email not provided by Facebook. Please allow email access."
}

500 — json

{
  "error": "Error processing Facebook authentication: EXAMPLE"
}

500 — json

{
  "error": "Failed to create user in external database"
}

`/e/v1/developer/external-providers/`

Manage workspace social-provider credentials.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_external_providers.

Optional list filters workspace_id and oauth_client where shown below; detail routes check resource ownership.

Request / response schema: ExternalProvider.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`oauth_client`	`not supplied`
query	`workspace_id`	`not supplied`

Related schemas: ExternalProvider.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Example",
    "provider_type": "google",
    "client_id": "EXAMPLE_CLIENT_ID",
    "client_secret_masked": "EXAMPLE_CLIENT_SECRET_MASKED",
    "is_active": true,
    "created_at": "2026-10-26T12:00:00Z",
    "updated_at": "2026-10-26T12:00:00Z",
    "developer_id": "EXAMPLE_DEVELOPER_ID",
    "workspace": "11111111-1111-4111-8111-111111111111"
  }
]

403 — json

{
  "error": "Workspace not found or access denied"
}

404 — json

{
  "error": "Workspace not found"
}

500 — json

{
  "error": "Failed to fetch providers: EXAMPLE"
}

POST

Required developer-token scope: write_external_providers.

Supply workspace explicitly and the required fields in the linked schema. Plan features, quotas and resource ownership apply. Provider creation requires a resolved user-plan ID and social-provider access on your plan.

Request / response schema: ExternalProvider.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
body	`workspace`	`not supplied`
body	`provider_type`	`'provider'`

Related schemas: ExternalProvider.

Example request body:

{
  "name": "Google sign-in",
  "workspace": "11111111-1111-4111-8111-111111111111",
  "provider_type": "google",
  "client_id": "PROVIDER_CLIENT_ID",
  "client_secret": "PROVIDER_CLIENT_SECRET"
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

201 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example",
  "provider_type": "google",
  "client_id": "EXAMPLE_CLIENT_ID",
  "client_secret_masked": "EXAMPLE_CLIENT_SECRET_MASKED",
  "is_active": true,
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111"
}

400 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

400 — json

{
  "error": "user_plan_id parameter is required (or provide workspace with active_plan_id)"
}

400 — json

{
  "error": "Validation error: EXAMPLE"
}

400 — json

{
  "error": "A EXAMPLE configuration already exists for this user"
}

403 — json

{
  "error": "You do not have access to this plan or the plan does not exist"
}

403 — json

{
  "error": "Feature not enabled",
  "feature": "external_providers_enabled",
  "message": "External provider configuration is not enabled in your current plan",
  "upgrade_message": "Please upgrade your plan to access external OAuth providers"
}

403 — json

{
  "error": "External provider creation limit exceeded",
  "feature": "max_external_providers",
  "current_count": 1,
  "limit": 1,
  "message": "EXAMPLE_MESSAGE",
  "upgrade_message": "Please upgrade your Syauth plan to create more external providers"
}

500 — json

{
  "error": "Failed to create provider: EXAMPLE"
}

`/e/v1/developer/external-providers/{provider_id}/`

Manage workspace social-provider credentials.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_external_providers.

Optional list filters workspace_id and oauth_client where shown below; detail routes check resource ownership.

Path parameters: provider_id (uuid, required).

Request / response schema: ExternalProvider.

Related schemas: ExternalProvider.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example",
  "provider_type": "google",
  "client_id": "EXAMPLE_CLIENT_ID",
  "client_secret_masked": "EXAMPLE_CLIENT_SECRET_MASKED",
  "is_active": true,
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111"
}

PATCH

Required developer-token scope: write_external_providers.

Partial update using the linked schema; resource ownership applies.

Path parameters: provider_id (uuid, required).

Request / response schema: ExternalProvider.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	`oauth_client`	`not supplied`

Related schemas: ExternalProvider.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example",
  "provider_type": "google",
  "client_id": "EXAMPLE_CLIENT_ID",
  "client_secret_masked": "EXAMPLE_CLIENT_SECRET_MASKED",
  "is_active": true,
  "created_at": "2026-10-26T12:00:00Z",
  "updated_at": "2026-10-26T12:00:00Z",
  "developer_id": "EXAMPLE_DEVELOPER_ID",
  "workspace": "11111111-1111-4111-8111-111111111111"
}

400 — json

JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.

500 — json

{
  "error": "Error updating provider: EXAMPLE"
}

DELETE

Required developer-token scope: write_external_providers.

No body; resource ownership applies.

Path parameters: provider_id (uuid, required).

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

204 — json

No response body.

500 — json

{
  "error": "Error deleting provider: EXAMPLE"
}

`/e/v1/oauth/clients/{client_id}/providers/`

List configured providers available to a client.

GET

Public path uses public client_id. Returned data is suitable for login buttons; provider credentials remain private.

Path parameters: client_id (str, required).

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Example",
    "provider_type": "EXAMPLE_PROVIDER_TYPE",
    "is_active": true
  }
]

404 — json

{
  "error": "OAuth client not found"
}

500 — json

{
  "error": "Failed to fetch external providers"
}

/e/v1/developer/templates/​

GET​

POST​

/e/v1/developer/templates/{template_id}/​

GET​

PATCH​

DELETE​

/e/v1/oauth/google/​

GET​

/e/v1/oauth/google/callback/​

GET​

/e/v1/oauth/github/​

GET​

/e/v1/oauth/github/callback/​

GET​

/e/v1/oauth/linkedin/​

GET​

/e/v1/oauth/linkedin/callback/​

GET​

/e/v1/oauth/facebook/​

GET​

/e/v1/oauth/facebook/callback/​

GET​

/e/v1/developer/external-providers/​

GET​

POST​

/e/v1/developer/external-providers/{provider_id}/​

GET​

PATCH​

DELETE​

/e/v1/oauth/clients/{client_id}/providers/​

GET​

`/e/v1/developer/templates/`

GET

POST

`/e/v1/developer/templates/{template_id}/`

GET

PATCH

DELETE

`/e/v1/oauth/google/`

GET

`/e/v1/oauth/google/callback/`

GET

`/e/v1/oauth/github/`

GET

`/e/v1/oauth/github/callback/`

GET

`/e/v1/oauth/linkedin/`

GET

`/e/v1/oauth/linkedin/callback/`

GET

`/e/v1/oauth/facebook/`

GET

`/e/v1/oauth/facebook/callback/`

GET

`/e/v1/developer/external-providers/`

GET

POST

`/e/v1/developer/external-providers/{provider_id}/`

GET

PATCH

DELETE

`/e/v1/oauth/clients/{client_id}/providers/`

GET