Applications and branding
An OAuth client represents an application. Management paths use the resource id; authorization requests use its public client_id. Keep confidential client secrets on your server.
API conventions · All endpoints · Schemas
/e/v1/developer/clients/
List or create OAuth clients.
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_clients.
Optional query workspace_id (accessible workspace) and legacy user_plan_id.
Request fields (combine with the requirements and schema above):
| Location | Field | Fallback when absent |
|---|---|---|
| query | user_plan_id | not supplied |
| query | workspace_id | not supplied |
Related schemas: OAuthClient.
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",
"client_id": "EXAMPLE_CLIENT_ID",
"client_secret": "***HIDDEN***",
"client_type": "confidential",
"redirect_uris": "http://127.0.0.1:8080/callback",
"allowed_grant_types": "authorization_code,refresh_token",
"allowed_response_types": "code",
"allowed_scopes": "openid,profile,email",
"auto_approve": true,
"created_at": "2026-10-26T12:00:00Z",
"updated_at": "2026-10-26T12:00:00Z",
"is_active": true,
"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_clients.
Required OAuthClient schema fields include name, redirect_uris, allowed_grant_types, allowed_response_types and allowed_scopes. Supply workspace UUID and client_type (public or confidential). Supply user_plan_id query or a workspace with active plan; fallback resolution can use the account plan. Strings or arrays are accepted for delimited fields. Creation enforces the OAuth-client quota.
Request / response schema: OAuthClient.
Request fields (combine with the requirements and schema above):
| Location | Field | Fallback when absent |
|---|---|---|
| body | workspace | not supplied |
Related schemas: OAuthClient.
Example request body:
{
"name": "Local app",
"workspace": "11111111-1111-4111-8111-111111111111",
"client_type": "public",
"redirect_uris": [
"http://127.0.0.1:8080/callback"
],
"allowed_grant_types": [
"authorization_code",
"refresh_token"
],
"allowed_response_types": [
"code"
],
"allowed_scopes": [
"openid",
"profile",
"email"
]
}
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",
"client_id": "EXAMPLE_CLIENT_ID",
"client_secret": "***HIDDEN***",
"client_type": "confidential",
"redirect_uris": "http://127.0.0.1:8080/callback",
"allowed_grant_types": "authorization_code,refresh_token",
"allowed_response_types": "code",
"allowed_scopes": "openid,profile,email",
"auto_approve": true,
"created_at": "2026-10-26T12:00:00Z",
"updated_at": "2026-10-26T12:00:00Z",
"is_active": true,
"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)"
}
403 — json
{
"error": "You do not have access to this plan or the plan does not exist"
}
403 — json
{
"error": "OAuth client creation limit exceeded",
"feature": "max_oauth_clients",
"current_count": 1,
"limit": 1,
"message": "EXAMPLE_MESSAGE",
"upgrade_message": "Please upgrade your Syauth plan to create more OAuth clients"
}
500 — json
{
"error": "Failed to create client: EXAMPLE"
}
/e/v1/developer/clients/{client_id}/
Manage an OAuth client using its database row UUID.
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_clients.
Creating-developer ownership check applies.
Path parameters: client_id (uuid, required).
Related schemas: OAuthClient.
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",
"client_id": "EXAMPLE_CLIENT_ID",
"client_secret": "***HIDDEN***",
"client_type": "confidential",
"redirect_uris": "http://127.0.0.1:8080/callback",
"allowed_grant_types": "authorization_code,refresh_token",
"allowed_response_types": "code",
"allowed_scopes": "openid,profile,email",
"auto_approve": true,
"created_at": "2026-10-26T12:00:00Z",
"updated_at": "2026-10-26T12:00:00Z",
"is_active": true,
"developer_id": "EXAMPLE_DEVELOPER_ID",
"workspace": "11111111-1111-4111-8111-111111111111"
}
PUT
Required developer-token scope: write_clients.
Partial OAuthClient schema update; this route has PUT but no PATCH.
Path parameters: client_id (uuid, required).
Request / response schema: OAuthClient.
Related schemas: OAuthClient.
Example request body:
{
"name": "Renamed app"
}
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",
"client_id": "EXAMPLE_CLIENT_ID",
"client_secret": "***HIDDEN***",
"client_type": "confidential",
"redirect_uris": "http://127.0.0.1:8080/callback",
"allowed_grant_types": "authorization_code,refresh_token",
"allowed_response_types": "code",
"allowed_scopes": "openid,profile,email",
"auto_approve": true,
"created_at": "2026-10-26T12:00:00Z",
"updated_at": "2026-10-26T12:00:00Z",
"is_active": true,
"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.
DELETE
Required developer-token scope: write_clients.
No body. Deletes the selected client.
Path parameters: client_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.
/e/v1/developer/clients/{client_id}/reset-secret/
Rotate a confidential client secret.
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.
POST
Required developer-token scope: write_clients.
No body. The new plaintext secret is returned once. Public clients receive 400. Update consumers before discarding the response.
Path parameters: client_id (uuid, required).
Success and error response examples
Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.
200 — json
{
"client_id": "EXAMPLE_CLIENT_ID",
"client_secret": "***HIDDEN***"
}
400 — json
{
"error": "Only confidential clients have secrets"
}
404 — json
{
"error": "Client not found"
}
/e/v1/developer/clients/{client_id}/branding/
Manage hosted-login branding for a client.
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_clients.
Returns branding or JSON null when absent.
Path parameters: client_id (uuid, required).
Related schemas: OAuthClientBranding.
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",
"oauth_client": "11111111-1111-4111-8111-111111111111",
"logo_url": "EXAMPLE_LOGO_URL",
"company_name": "EXAMPLE_COMPANY_NAME",
"primary_color": "EXAMPLE_PRIMARY_COLOR",
"secondary_color": "EXAMPLE_SECONDARY_COLOR",
"background_color": "EXAMPLE_BACKGROUND_COLOR",
"theme": "light",
"custom_css": "EXAMPLE_CUSTOM_CSS",
"show_social_logins": true,
"terms_url": "https://app.example.test/callback",
"privacy_url": "https://app.example.test/callback",
"created_at": "2026-10-26T12:00:00Z",
"updated_at": "2026-10-26T12:00:00Z"
}
200 — json
JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.
POST
Required developer-token scope: write_clients.
OAuthClientBranding schema; client association is set from the URL. Existing branding returns 400; use PUT to update.
Path parameters: client_id (uuid, required).
Request / response schema: OAuthClientBranding.
Related schemas: OAuthClientBranding.
Example request body:
{
"company_name": "Example company",
"primary_color": "#4F46E5",
"theme": "light"
}
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",
"oauth_client": "11111111-1111-4111-8111-111111111111",
"logo_url": "EXAMPLE_LOGO_URL",
"company_name": "EXAMPLE_COMPANY_NAME",
"primary_color": "EXAMPLE_PRIMARY_COLOR",
"secondary_color": "EXAMPLE_SECONDARY_COLOR",
"background_color": "EXAMPLE_BACKGROUND_COLOR",
"theme": "light",
"custom_css": "EXAMPLE_CUSTOM_CSS",
"show_social_logins": true,
"terms_url": "https://app.example.test/callback",
"privacy_url": "https://app.example.test/callback",
"created_at": "2026-10-26T12:00:00Z",
"updated_at": "2026-10-26T12:00:00Z"
}
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": "Branding already exists for this client. Use PUT to update."
}
PUT
Required developer-token scope: write_clients.
Partial branding update; returns 404 when no branding exists.
Path parameters: client_id (uuid, required).
Request / response schema: OAuthClientBranding.
Related schemas: OAuthClientBranding.
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",
"oauth_client": "11111111-1111-4111-8111-111111111111",
"logo_url": "EXAMPLE_LOGO_URL",
"company_name": "EXAMPLE_COMPANY_NAME",
"primary_color": "EXAMPLE_PRIMARY_COLOR",
"secondary_color": "EXAMPLE_SECONDARY_COLOR",
"background_color": "EXAMPLE_BACKGROUND_COLOR",
"theme": "light",
"custom_css": "EXAMPLE_CUSTOM_CSS",
"show_social_logins": true,
"terms_url": "https://app.example.test/callback",
"privacy_url": "https://app.example.test/callback",
"created_at": "2026-10-26T12:00:00Z",
"updated_at": "2026-10-26T12:00:00Z"
}
400 — json
JSON response varies with the request. See the operation requirements and linked schema; validation errors may be keyed by field name.
404 — json
{
"error": "Branding not found for this client. Use POST to create."
}
DELETE
Required developer-token scope: write_clients.
No body; remove existing branding.
Path parameters: client_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.
404 — json
{
"error": "Branding not found for this client."
}