Skip to content

Server Config

The server config endpoints let you read and modify Canvus Server settings at runtime -- authentication methods, SMTP email configuration, SAML single sign-on, and the server's external URL.

Unauthenticated and regular users can read a limited subset of settings (enough to render a login page). Administrators get full read-write access to all settings, including email/SMTP configuration and domain allow lists.

Read Settings

Returns the current server configuration. The response varies based on who is making the request:

  • Unauthenticated / regular users see only public-facing settings (authentication methods, external URL, server name).
  • Administrators see everything, including SMTP credentials, domain allow lists, and admin approval settings. The response includes "access": "rw" to indicate write access.

Request

  • Method: GET
  • URL: /api/v1/server-config
  • Authentication: None required (returns limited data); admin token returns full data
  • Streaming: Supported via ?subscribe query parameter

Response Fields (unauthenticated)

  • external_url -- The public-facing URL of the Canvus Server (e.g., "https://canvus.example.com").
  • server_name -- Optional display name for the server. Empty string if not set.
  • authentication -- Object containing authentication method configuration:
  • authentication.password.enabled -- Boolean. Whether password-based login is enabled.
  • authentication.password.sign_up_enabled -- Boolean. Whether self-registration via password is enabled.
  • authentication.qr_code.enabled -- Boolean. Whether QR code login is enabled (for Canvus desktop clients).
  • authentication.saml -- SAML SSO configuration (see below for fields).

Additional Response Fields (administrator only)

  • access -- Always "rw" for admin responses, indicating write access.
  • authentication.domain_allow_list -- Array of email domain strings. Only users with matching email domains can register. Empty array means no restriction.
  • authentication.require_admin_approval -- Boolean. Whether new user registrations require admin approval.
  • authentication.saml.acs_url -- SAML Assertion Consumer Service URL (auto-generated from external_url).
  • authentication.saml.enabled -- Boolean. Whether SAML SSO is enabled.
  • authentication.saml.idp_cert_finger_print -- SHA-256 fingerprint of the Identity Provider's certificate.
  • authentication.saml.idp_entity_id -- Entity ID of the SAML Identity Provider.
  • authentication.saml.idp_target_url -- SSO redirect URL of the Identity Provider.
  • authentication.saml.name_id_format -- SAML NameID format URI.
  • authentication.saml.sign_up_enabled -- Boolean. Whether SAML-based self-registration is enabled.
  • authentication.saml.sp_entity_id -- Service Provider entity ID (identifies Canvus to the IdP).
  • email -- Object containing SMTP/email configuration:
  • email.mail_sender_address -- Sender email address for outgoing mail.
  • email.mail_sender_name -- Display name for the sender.
  • email.mail_reply_to_address -- Reply-to email address. Empty string to omit.
  • email.mail_reply_to_name -- Reply-to display name.
  • email.smtp_host -- SMTP server hostname.
  • email.smtp_port -- SMTP server port (integer).
  • email.smtp_security -- Connection security. One of: "none", "ssl", "starttls".
  • email.smtp_username -- SMTP authentication username.
  • email.smtp_password -- SMTP authentication password. Returned as empty string for security.
  • email.smtp_allow_self_signed_certificates -- Boolean. Whether to accept self-signed TLS certificates from the SMTP server.

Example Request (unauthenticated)

curl https://canvus.example.com/api/v1/server-config

Example Response (unauthenticated)

{
  "authentication": {
    "password": {
      "enabled": true,
      "sign_up_enabled": false
    },
    "qr_code": {
      "enabled": true
    },
    "saml": {
      "acs_url": "https://canvus.example.com/users/login/saml/callback",
      "enabled": false,
      "idp_cert_finger_print": "",
      "idp_entity_id": "",
      "idp_target_url": "",
      "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
      "sign_up_enabled": false,
      "sp_entity_id": "canvus"
    }
  },
  "external_url": "https://canvus.example.com",
  "server_name": "Engineering Lab"
}

Example Request (administrator)

curl -H "Private-Token: glpat-a4F8kNz2Qx9bR7cY" \
  https://canvus.example.com/api/v1/server-config

Example Response (administrator)

{
  "access": "rw",
  "authentication": {
    "domain_allow_list": [
      "example.com",
      "partner.org"
    ],
    "password": {
      "enabled": true,
      "sign_up_enabled": false
    },
    "qr_code": {
      "enabled": true
    },
    "require_admin_approval": true,
    "saml": {
      "acs_url": "https://canvus.example.com/users/login/saml/callback",
      "enabled": true,
      "idp_cert_finger_print": "CA:F2:55:F8:F4:6D:E4:24:97:BE:3C:42:AC:CC:BA:41:51:D9:8F:EB:A3:1E:73:77:AB:5C:24:33:A3:5A:20:65",
      "idp_entity_id": "https://idp.example.com/saml/metadata",
      "idp_target_url": "https://idp.example.com/saml/sso",
      "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
      "sign_up_enabled": true,
      "sp_entity_id": "canvus"
    }
  },
  "email": {
    "mail_reply_to_address": "support@example.com",
    "mail_reply_to_name": "Canvus Support",
    "mail_sender_address": "noreply@example.com",
    "mail_sender_name": "Canvus Server",
    "smtp_allow_self_signed_certificates": false,
    "smtp_host": "smtp.example.com",
    "smtp_password": "",
    "smtp_port": 587,
    "smtp_security": "starttls",
    "smtp_username": "noreply@example.com"
  },
  "external_url": "https://canvus.example.com",
  "server_name": "Engineering Lab"
}

Streaming Example

To receive live updates when settings change, add ?subscribe to the URL. The connection stays open and the server sends newline-delimited JSON whenever a setting is modified.

curl -N -H "Private-Token: glpat-a4F8kNz2Qx9bR7cY" \
  "https://canvus.example.com/api/v1/server-config?subscribe"

Error Responses

  • 500 Internal Server Error -- {"msg": "error description"}

Change Settings

Updates one or more server settings. Send only the fields you want to change -- omitted fields are left unchanged. The response contains the full configuration after the update.

Request

  • Method: PATCH
  • URL: /api/v1/server-config
  • Authentication: Admin required (Private-Token header)
  • Content-Type: application/json
  • Streaming: Not applicable

Request Body

A JSON object with the same structure as the GET response. Include only the fields you want to change. Nested objects are merged, not replaced -- you can update a single nested field without affecting siblings.

Example: Disable self-registration and restrict to a domain

curl -X PATCH \
  -H "Private-Token: glpat-a4F8kNz2Qx9bR7cY" \
  -H "Content-Type: application/json" \
  -d '{
    "authentication": {
      "domain_allow_list": ["example.com"],
      "password": {
        "sign_up_enabled": false
      }
    }
  }' \
  https://canvus.example.com/api/v1/server-config

Example: Configure SMTP

curl -X PATCH \
  -H "Private-Token: glpat-a4F8kNz2Qx9bR7cY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": {
      "smtp_host": "smtp.example.com",
      "smtp_port": 587,
      "smtp_security": "starttls",
      "smtp_username": "noreply@example.com",
      "smtp_password": "s3cret-smtp-p4ss",
      "mail_sender_address": "noreply@example.com",
      "mail_sender_name": "Canvus Server"
    }
  }' \
  https://canvus.example.com/api/v1/server-config

Example Response

Returns the full server configuration (same structure as the admin GET response above).

Error Responses

  • 400 Bad Request -- {"msg": "error description"} -- Invalid field value or malformed JSON.
  • 401 Unauthorized -- {"msg": "error description"} -- Missing or invalid authentication token.
  • 403 Forbidden -- {"msg": "error description"} -- Authenticated user is not an administrator.

Reload TLS Certificates

Tells the server to reload its TLS certificates from disk without restarting. Use this after replacing certificate files on the server to pick up the new certificates immediately.

Request

  • Method: POST
  • URL: /api/v1/server-config/reload-certs
  • Authentication: Admin required (Private-Token header)
  • Streaming: Not applicable

Example Request

curl -X POST \
  -H "Private-Token: glpat-a4F8kNz2Qx9bR7cY" \
  https://canvus.example.com/api/v1/server-config/reload-certs

Error Responses

  • 401 Unauthorized -- {"msg": "error description"} -- Missing or invalid authentication token.
  • 403 Forbidden -- {"msg": "error description"} -- Authenticated user is not an administrator.
  • 500 Internal Server Error -- {"msg": "error description"} -- Certificate reload failed (e.g., invalid certificate file).

Send Test Email

Sends a test email to the email address of the authenticated administrator making the request. Use this to verify that your SMTP configuration is working correctly after changing email settings.

Request

  • Method: POST
  • URL: /api/v1/server-config/send-test-email
  • Authentication: Admin required (Private-Token header)
  • Streaming: Not applicable

Example Request

curl -X POST \
  -H "Private-Token: glpat-a4F8kNz2Qx9bR7cY" \
  https://canvus.example.com/api/v1/server-config/send-test-email

The test email is sent to the email address associated with the admin account that owns the access token.

Error Responses

  • 401 Unauthorized -- {"msg": "error description"} -- Missing or invalid authentication token.
  • 403 Forbidden -- {"msg": "error description"} -- Authenticated user is not an administrator.
  • 500 Internal Server Error -- {"msg": "error description"} -- Email sending failed (e.g., SMTP not configured, server unreachable, authentication failed).