server/docs/api/roles.md

# Roles API

The Roles API lets users manage roles given to them by administrators. This API is available to all users.

> [!WARNING]
> The API for **administrators** is different (and unimplemented): this is the API for **users**.
>
> Furthermore, users can only manage roles if they have the `roles` permission, and the role they wish to manage does not have a higher priority than their highest priority role.

## Priorities

Roles have a priority, which determines the order in which they are applied. Roles with higher priorities take precedence over roles with lower priorities.

Additionally, users cannot remove or add roles with a higher priority than their highest priority role.

## Visibility

Roles can be visible or invisible. Invisible roles are not shown to users in the UI, but they can still be managed via the API.

> [!WARNING]
> All roles assigned to a user are public information and can be retrieved via the API. The visibility of a role only affects whether it is shown in the UI, which clients can choose to respect or not.

## Permissions

```ts
// Last updated: 2024-06-07
// Search for "RolePermissions" in the source code (GitHub search bar) for the most up-to-date version
enum RolePermissions {
    MANAGE_NOTES = "notes",
    MANAGE_OWN_NOTES = "owner:note",
    MANAGE_ACCOUNTS = "accounts",
    MANAGE_OWN_ACCOUNT = "owner:account",
    MANAGE_EMOJIS = "emojis",
    MANAGE_OWN_EMOJIS = "owner:emoji",
    MANAGE_MEDIA = "media",
    MANAGE_OWN_MEDIA = "owner:media",
    MANAGE_BLOCKS = "blocks",
    MANAGE_OWN_BLOCKS = "owner:block",
    MANAGE_FILTERS = "filters",
    MANAGE_OWN_FILTERS = "owner:filter",
    MANAGE_MUTES = "mutes",
    MANAGE_OWN_MUTES = "owner:mute",
    MANAGE_REPORTS = "reports",
    MANAGE_OWN_REPORTS = "owner:report",
    MANAGE_SETTINGS = "settings",
    MANAGE_OWN_SETTINGS = "owner:settings",
    MANAGE_ROLES = "roles",
    IGNORE_RATE_LIMITS = "ignore_rate_limits",
    IMPERSONATE = "impersonate",
    MANAGE_INSTANCE = "instance",
    MANAGE_INSTANCE_FEDERATION = "instance:federation",
    MANAGE_INSTANCE_SETTINGS = "instance:settings",
    OAUTH = "oauth",
}
```

### Manage Roles

The `roles` permission allows the user to manage roles, including adding and removing roles from themselves. This permission is required to use the Roles API.

### Impersonate

The `impersonate` permission allows the user to impersonate other users (logging in with their credentials). This is a dangerous permission and should be used with caution.

### Manage Instance

The `instance` permission allows the user to manage the instance, including viewing logs, restarting the instance, and more.

### Manage Instance Federation

The `instance:federation` permission allows the user to manage the instance's federation settings, including blocking and unblocking other instances.

### Manage Instance Settings

The `instance:settings` permission allows the user to manage the instance's settings, including changing the instance's name, description, and more.

### OAuth2

The `oauth` permission is required for users to log in to the instance. Users who do not have this permission will not be able to log in.

## Get Roles

```http
GET /api/v1/roles
```

Retrieves a list of roles that the user has.

### Response

```ts
// 200 OK
{
    id: string;
    name: string;
    permissions: RolePermissions[];
    priority: number;
    description: string | null;
    visible: boolean;
    icon: string | null
}[];
```

## Get Role

```http
GET /api/v1/roles/:id
```

Retrieves information about a role.

### Response

```ts
// 200 OK
{
    id: string;
    name: string;
    permissions: RolePermissions[];
    priority: number;
    description: string | null;
    visible: boolean;
    icon: string | null
}
```

## Add Role

```http
POST /api/v1/roles/:id
```

Adds the role with the given ID to the user making the request.

### Response

```ts
// 204 No Content
```

## Remove Role

```http
DELETE /api/v1/roles/:id
```

Removes the role with the given ID from the user making the request.

### Response

```ts
// 204 No Content
```