> For the complete documentation index, see [llms.txt](https://developerdocs.instructure.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developerdocs.instructure.com/services/canvas/resources/discovery_pages.md).

# Discovery Pages

#### A DiscoveryPage object looks like: <a href="#discoverypage" id="discoverypage"></a>

```js
// 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 href="#discoverypageentry" id="discoverypageentry"></a>

```js
// 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](#method.discovery_pages_api.show) <a href="#method.discovery_pages_api.show" id="method.discovery_pages_api.show"></a>

[DiscoveryPagesApiController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/discovery_pages_api_controller.rb)

#### `GET /api/v1/discovery_pages`

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

Get the discovery page configuration for the domain root account.

#### Example Request:

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

#### Example Response:

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

Returns a [DiscoveryPage](#discoverypage) object.

## [Update Discovery Page](#method.discovery_pages_api.upsert) <a href="#method.discovery_pages_api.upsert" id="method.discovery_pages_api.upsert"></a>

[DiscoveryPagesApiController#upsert](https://github.com/instructure/canvas-lms/blob/master/app/controllers/discovery_pages_api_controller.rb)

#### `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:

```bash
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:

```js
{
  "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](#discoverypage) object.

## [Generate Discovery Page Preview Token](#method.discovery_pages_api.token) <a href="#method.discovery_pages_api.token" id="method.discovery_pages_api.token"></a>

[DiscoveryPagesApiController#token](https://github.com/instructure/canvas-lms/blob/master/app/controllers/discovery_pages_api_controller.rb)

#### `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:

```bash
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](https://github.com/instructure/canvas-lms).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developerdocs.instructure.com/services/canvas/resources/discovery_pages.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.