🚀 Heads up: Our API Docs Have Moved!
We have relocated to Instructure Developer Documentation Portal. 🎉 Please update your bookmarks. This page will automatically redirect after July 1, 2026.

Discovery Pages API

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
}

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",
  // URL to an icon image for this provider button
  "icon_url": "https://example.com/icons/students.svg"
}

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.

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_url": "https://example.com/icons/students.svg"
      }
    ],
    "secondary": [
      {
        "authentication_provider_id": 3,
        "label": "Admins"
      }
    ]
  }
}
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.

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_url] string

URL to an icon image 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_url] string

URL to an icon image for this authentication provider button.

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_url": "https://example.com/icons/students.svg"
        },
        {
          "authentication_provider_id": 2,
          "label": "Faculty",
          "icon_url": "https://example.com/icons/faculty.svg"
        }
      ],
      "secondary": [
        {
          "authentication_provider_id": 3,
          "label": "Admins"
        }
      ]
    }
  }'

Example Response:

{
  "discovery_page": {
    "primary": [
      {
        "authentication_provider_id": 1,
        "label": "Students",
        "icon_url": "https://example.com/icons/students.svg"
      },
      {
        "authentication_provider_id": 2,
        "label": "Faculty",
        "icon_url": "https://example.com/icons/faculty.svg"
      }
    ],
    "secondary": [
      {
        "authentication_provider_id": 3,
        "label": "Admins"
      }
    ]
  }
}
Returns a DiscoveryPage object