[activities] add documentation for get_activity_instance (#6981)

* Add docs for activity instance validation

* update to for new endpoint and shape

* touch up some stuff advaith noticed

* first pass Get Application Activity Instance endpoint

* add warning about channel_id and future deprecation

* fix url in curl examples

* update example in development guide

* remove channel_id, add tables for Activity Instance Object, Activity Location Object, Activity Location Kind Enum

* cleanup that json

* pnpm run fix:tables

* :s/activity-instance/activity-instances/g

* add Type column to Application Location table

---------

Co-authored-by: Matt Hova <[email protected]>

Author: afgiel

docs/activities/Development_Guides.mdx

@@ -94,6 +94,9 @@ These guides include suggested development practices, SDK commands, and user flo
   <Card title="Render Avatars and Names" link="#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/render-avatars-and-names">
     Retrieve and render the usernames and avatars of users connected to your application.
   </Card>
+  <Card title="Preventing Unwanted Activity Sessions" link="#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/preventing-unwanted-activity-sessions">
+    Validating activity sessions are via a Discord client before adding them to an instance's session.
+  </Card>
 </Container>
 
 ## Assets & Metadata
@@ -887,6 +890,29 @@ This example is being done entirely on the client, however, a more common patter
 
 ---
 
+### Preventing unwanted activity sessions
+
+Activities are surfaced through iframes in the Discord app. The activity website itself is publicly reachable at `<application_id>.discordsays.com`. Activities will expect to be able to communicate with Discord's web or mobile client via the Discord SDK's RPC protocol. If a user loads the activity's website in a normal browser, the Discord RPC server will not be present, and the activity will likely fail in some way.
+
+It is theoretically possible for a malicious client to mock Discord's RPC protocol or load one activity website when launching another. Because the activity is loaded inside Discord, the RPC protocol is active, and the activity is none the wiser.
+
+To enable an activity to "lock down" activity access, we encourage utilizing the `get_activity_instance` API, found at `discord.com/api/applications/<application_id>/activity-instances/<instance_id>'`. The route requires a Bot token of the application. It returns a serialized active activity instance for the given application, if found, otherwise it returns a 404. Here are two example responses:
+
+```javascript
+curl https://discord.com/api/applications/1215413995645968394/activity-instances/i-1234567890-gc-912952092627435520-912954213460484116 -H 'Authorization: Bot <bot token>'
+{"message": "404: Not Found", "code": 0}
+
+curl https://discord.com/api/applications/1215413995645968394/activity-instances/i-1276580072400224306-gc-912952092627435520-912954213460484116 -H 'Authorization: Bot <bot token>'
+{"application_id":"1215413995645968394","instance_id":"i-1276580072400224306-gc-912952092627435520-912954213460484116","launch_id":"1276580072400224306","location":{"id":"gc-912952092627435520-912954213460484116","kind":"gc","channel_id":"912954213460484116","guild_id":"912952092627435520"},"users":["205519959982473217"]}
+```
+
+With this API, the activity's backend can verify that a client is in fact in an instance of that activity before allowing the client to participate in any meaningful gameplay. How an activity implements "session verification" is left to the developer's discretion. The solution can be as granular as gating specific features or as binary as not returning the activity HTML except for valid sessions.
+
+In the below flow diagram, we show how the server can deliver the activity website, only for valid users in a valid activity instance:
+![application-test-mode-prod](activities/activity-instance-validation.jpg)
+
+---
+
 ### Setting Up Activity Metadata
 
 The Activity Shelf is where users can see what Activities can be played. It has various metadata and art assets that can be configured.

docs/resources/Application.md

@@ -236,4 +236,56 @@ Edit properties of the app associated with the requesting bot user. Only propert
 
 \* Only limited intent flags (`GATEWAY_PRESENCE_LIMITED`, `GATEWAY_GUILD_MEMBERS_LIMITED`, and `GATEWAY_MESSAGE_CONTENT_LIMITED`) can be updated via the API.
 
-\*\* To update an Interactions endpoint URL via the API, the URL must be valid according to the [Receiving an Interaction](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/receiving-an-interaction) documentation.
+\*\* To update an Interactions endpoint URL via the API, the URL must be valid according to the [Receiving an Interaction](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/receiving-an-interaction) documentation.
+
+## Get Application Activity Instance % GET /applications/{application.id#DOCS_RESOURCES_APPLICATION/application-object}/activity-instances/{instance_id}
+
+Returns a serialized activity instance, if it exists. Useful for [preventing unwanted activity sessions](#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/preventing-unwanted-activity-sessions).
+
+
+###### Example Activity Instance
+
+```json
+{
+  "application_id": "1215413995645968394",
+  "instance_id": "i-1276580072400224306-gc-912952092627435520-912954213460484116",
+  "launch_id": "1276580072400224306",
+  "location": {
+    "id": "gc-912952092627435520-912954213460484116",
+    "kind": "gc",
+    "channel_id": "912954213460484116",
+    "guild_id": "912952092627435520"
+  },
+  "users": ["205519959982473217"],
+}
+```
+
+###### Activity Instance Object
+
+| Field          | Type                                                                                                        | Description                                                                              |
+|----------------|-------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
+| application_id | snowflake                                                                                                   | [Application](#DOCS_RESOURCES_APPLICATION/application-object) ID                         |
+| instance_id    | string                                                                                                      | Activity [Instance](#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/activity-instance-management) ID |
+| launch_id      | snowflake                                                                                                   | Unique identifier for the launch                                                         |
+| location       | [Activity Location](#DOCS_RESOURCES_APPLICATION/get-application-activity-instance-activity-location-object) | The Location the instance is runnning in                                                 |
+| users          | array of snowflakes, [user](#DOCS_RESOURCES_USER/user-object) ids                                           | The IDs of the Users currently connected to the instance                                 |
+
+
+
+###### Activity Location Object
+
+The Activity Location is an object that describes the location in which an activity instance is running.
+
+| Field      | Type                                                                                                                     | Description                                                     |
+|------------|--------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
+| id         | string                                                                                                                   | The unique identifier for the location                          |
+| kind       | [Activity Location Kind Enum](#DOCS_RESOURCES_APPLICATION/get-application-activity-instance-activity-location-kind-enum) | Enum describing kind of location                                |
+| channel_id | snowflake                                                                                                                | The id of the [Channel](#DOCS_RESOURCES_CHANNEL/channel-object) |
+| guild_id?  | ?snowflake                                                                                                               | The id of the [Guild](#DOCS_RESOURCES_GUILD/guild-object)       |
+
+###### Activity Location Kind Enum
+
+| Enum | Description                                            |
+|------|--------------------------------------------------------|
+| 'gc' | The Location is a Guild Channel                        |
+| 'pc' | The Location is a Private Channel, such as a DM or GDM |