# 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).