Discovery Pages

A DiscoveryPage object looks like:

// Configuration for the login discovery page
{
  // Primary authentication provider buttons displayed prominently
  "primary": null,
  // Secondary authentication provider buttons displayed less prominently
  "secondary": null,
  // Whether the discovery page is enabled
  "active": null
}

A DiscoveryPageEntry object looks like:

// A single authentication provider entry on the discovery page
{
  // The ID of the authentication provider
  "authentication_provider_id": 1,
  // The display label for this provider button
  "label": "Students",
  // Icon key for this provider button
  "icon": "google"
}

Get Discovery Page

DiscoveryPagesApiController#show

GET /api/v1/discovery_pages

Scope: url:GET|/api/v1/discovery_pages

Get the discovery page configuration for the domain root account.

Returns labels exactly as stored, with no HTML-escaping applied. Callers are responsible for escaping on render (the admin React UI does this via JSX auto-escaping).

Example Request:

curl 'https://<canvas>/api/v1/discovery_pages' \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "discovery_page": {
    "primary": [
      {
        "authentication_provider_id": 1,
        "label": "Students",
        "icon": "google"
      }
    ],
    "secondary": [
      {
        "authentication_provider_id": 3,
        "label": "Admins"
      }
    ],
    "active": true
  }
}

Returns a DiscoveryPage object.

Update Discovery Page

DiscoveryPagesApiController#upsert

PUT /api/v1/discovery_pages

Scope: url:PUT|/api/v1/discovery_pages

Update or create the discovery page configuration for the domain root account. This is a full replacement - provide the complete configuration including primary, secondary, and active fields. Any fields omitted will be removed.

Request Parameters:

Parameter	Type	Description
discovery_page[primary][][authentication_provider_id]	Required integer	The ID of an active authentication provider for this account.
discovery_page[primary][][label]	Required string	The display label for this authentication provider button.
discovery_page[primary][][icon]	string	Icon key for this authentication provider button.
discovery_page[secondary][][authentication_provider_id]	Required integer	The ID of an active authentication provider for this account.
discovery_page[secondary][][label]	Required string	The display label for this authentication provider button.
discovery_page[secondary][][icon]	string	Icon key for this authentication provider button.
discovery_page[active]	boolean	Whether the discovery page is enabled. Defaults to false if not provided.

Example Request:

curl -X PUT 'https://<canvas>/api/v1/discovery_pages' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "discovery_page": {
      "primary": [
        {
          "authentication_provider_id": 1,
          "label": "Students",
          "icon": "google"
        },
        {
          "authentication_provider_id": 2,
          "label": "Faculty",
          "icon": "okta"
        }
      ],
      "secondary": [
        {
          "authentication_provider_id": 3,
          "label": "Admins"
        }
      ],
      "active": true
    }
  }'

Example Response:

{
  "discovery_page": {
    "primary": [
      {
        "authentication_provider_id": 1,
        "label": "Students",
        "icon": "google"
      },
      {
        "authentication_provider_id": 2,
        "label": "Faculty",
        "icon": "okta"
      }
    ],
    "secondary": [
      {
        "authentication_provider_id": 3,
        "label": "Admins"
      }
    ],
    "active": true
  }
}

Returns a DiscoveryPage object.

Generate Discovery Page Preview Token

DiscoveryPagesApiController#token

POST /api/v1/discovery_pages/token

Scope: url:POST|/api/v1/discovery_pages/token

Returns a short-lived RS256-signed JWT containing the discovery page button link configuration, suitable for sending to the identity service preview iframe via postMessage.

A discovery_page configuration must be provided in the request body. Omitting it returns a 400 Bad Request.

Request Parameters:

Parameter	Type	Description
discovery_page[primary][][authentication_provider_id]	Required integer	The ID of an active authentication provider for this account.
discovery_page[primary][][label]	string	The display label for this authentication provider button.
discovery_page[primary][][icon]	string	Icon key for this authentication provider button.
discovery_page[secondary][][authentication_provider_id]	integer	The ID of an active authentication provider for this account.
discovery_page[secondary][][label]	string	The display label for this authentication provider button.
discovery_page[secondary][][icon]	string	Icon key for this authentication provider button.

Example Request:

curl -X POST 'https://<canvas>/api/v1/discovery_pages/token' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "discovery_page": {
      "primary": [
        {
          "authentication_provider_id": 1,
          "label": "Students",
          "icon": "google"
        }
      ],
      "secondary": []
    }
  }'

---

This documentation is generated directly from the Canvas LMS source code, available on Github.