Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
6.4 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Admin applications
description: Look up OAuth2 applications and their bots, and transfer ownership.
---

import RouteHeader from '@/components/RouteHeader.astro';

An application is an OAuth2 client that can have one bot account. These routes look up any application and transfer its ownership. To manage your own applications, use the public [Applications](/http-api/applications/) resource.

## Admin application object

Admin routes return applications in this structure. When the application has a bot, `bot_user_id` is the same as `id`. The object never has the client secret or bot token, only whether each one is set.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| id | snowflake | The ID of the application |
| name | string | The display name (1-256 characters) |
| owner_user_id | snowflake | The ID of the owning account |
| owner_username<sup>1</sup> | ?string | The username of the owner |
| owner_global_name<sup>1</sup> | ?string | The display name of the owner |
| owner_discriminator<sup>1</sup> | ?string | The discriminator of the owner, as four digits |
| bot_user_id | ?snowflake | The ID of the bot account, or null when there is no bot |
| bot_username<sup>2</sup> | ?string | The username of the bot |
| bot_global_name<sup>2</sup> | ?string | The display name of the bot |
| bot_discriminator<sup>2</sup> | ?string | The discriminator of the bot, as four digits |
| bot_is_public | boolean | Whether an account other than the owner can add the bot |
| bot_require_code_grant | boolean | Whether adding the bot needs a completed authorization code grant |
| oauth2_redirect_uris | array[string] | The registered OAuth2 redirect URIs (at most 10) |
| has_client_secret | boolean | Whether the application has a client secret |
| has_bot_token | boolean | Whether the application has a bot token |
| bot_token_preview | ?string | The first 8 characters of the bot token's secret part |
| bot_token_created_at | ?ISO8601 timestamp | When the bot token was created |
| client_secret_created_at | ?ISO8601 timestamp | When the client secret was created |
| version | integer | The version of the application, which goes up on each change (0-2147483647) |

<sup>1</sup> These are null when the owner account doesn't exist.

<sup>2</sup> These are null when there is no bot or the bot account doesn't exist.

### Example

```json
{
  "id": "1501314428688998182",
  "name": "Metronome",
  "owner_user_id": "1483920011884392448",
  "owner_username": "wren",
  "owner_global_name": "Wren",
  "owner_discriminator": "0042",
  "bot_user_id": "1501314428688998182",
  "bot_username": "metronome",
  "bot_global_name": null,
  "bot_discriminator": "0001",
  "bot_is_public": true,
  "bot_require_code_grant": false,
  "oauth2_redirect_uris": ["https://example.com/oauth2/callback"],
  "has_client_secret": true,
  "has_bot_token": true,
  "bot_token_preview": "kQ9xT2mA",
  "bot_token_created_at": "2026-02-11T09:14:02.117Z",
  "client_secret_created_at": "2026-02-11T09:13:58.004Z",
  "version": 7
}
```

## The built-in Admin application

The API has one built-in application for the Admin panel's OAuth2 client, with ID `1234567890123456789` and owner `0`. Its name is the instance name followed by ` Admin`. It exists only while the Admin client secret is set. [List applications](#list-applications) never returns it, and [transferring](#transfer-application-ownership) it fails with 403 `FORBIDDEN`.

## List applications

<RouteHeader method="GET" path="/v1/admin/applications" auditReason />

Returns the applications an account owns, or the applications whose bot is a member of a guild. Send exactly one of the query parameters. `owner_id` needs `application:list:by_owner` and `guild_id` needs `application:lookup`.

### Query parameters

| Field | Type | Description |
| --- | --- | --- |
| owner_id? | snowflake | Select the applications this account owns |
| guild_id? | snowflake | Select the applications whose bot is a member of this guild |

### Response body

| Field | Type | Description |
| --- | --- | --- |
| applications | array[[Admin application](#admin-application-object) object] | The selected applications |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The selected applications were returned |
| 404 | [error response](/admin-api/#error-response) | `UNKNOWN_USER` or `UNKNOWN_GUILD` when the ID doesn't exist |

The Admin audit entry has the action `list_user_applications` or `list_guild_applications` and the metadata key `application_count`.

The rate limit is 200 requests per minute, on the `admin:lookup` bucket.

## Get application

<RouteHeader method="GET" path="/v1/admin/applications/{application_id}" auditReason />

Returns one application, or null when no application has this ID. You need `application:lookup`.

### Response body

| Field | Type | Description |
| --- | --- | --- |
| application | ?[Admin application](#admin-application-object) object | The application |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The lookup completed |

The Admin audit entry has the action `get_application` and the metadata key `found`, plus `owner_user_id` and `bot_user_id` when the application has them.

The rate limit is 200 requests per minute, on the `admin:lookup` bucket.

## Transfer application ownership

<RouteHeader method="PATCH" path="/v1/admin/applications/{application_id}" auditReason />

Moves the application to another account and returns the updated [Admin application](#admin-application-object) object. You need `application:transfer_ownership`.

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| new_owner_id | snowflake | The account to transfer the application to |

### Response body

| Field | Type | Description |
| --- | --- | --- |
| application | [Admin application](#admin-application-object) object | The application after the transfer |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | Ownership was transferred |
| 403 | [error response](/admin-api/#error-response) | `FORBIDDEN` for the [built-in Admin application](#the-built-in-admin-application) |
| 404 | [error response](/admin-api/#error-response) | `UNKNOWN_APPLICATION` or `UNKNOWN_USER` for the new owner |

The Admin audit entry has the action `transfer_ownership` and the metadata keys `old_owner_id` and `new_owner_id`.

The rate limit is 100 requests per minute, on the `admin:guild:modify` bucket.