# Discovery Pages

{% hint style="warning" %}
**Welcome to Our New API Docs!** This is the new home for all things API (previously at [Canvas LMS REST API Documentation](https://api.instructure.com)).
{% endhint %}

## Discovery Pages API

**A DiscoveryPage object looks like:**

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

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