Skip to content

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

TypeScript fluxerfluxerapp
10.9 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Connections
description: Domain and Bluesky connections that appear on a user profile.
---

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

A connection links an account to a verified domain or Bluesky account. Visible connections appear in `connected_accounts` on the [full user profile object](/http-api/users/#full-user-profile-object).

Connection routes need a user token, and bot tokens and OAuth2 bearers get 403 `ACCESS_DENIED`. The one exception is [List connections](#list-connections), which accepts a bearer with the `connections` [scope](/http-api/oauth2/#oauth2-scopes).

An account can have up to 20 connections, and adding more returns 400 `CONNECTION_LIMIT_REACHED`.

## Connection object

A connection's [type](#connection-types) and `id` together identify it.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| id | string | The ID of the connection, unique within its type |
| type | string | [Connection type](#connection-types) |
| name | string | The domain or Bluesky handle |
| verified | boolean | Whether the connection is verified |
| visibility_flags | integer | [Connection visibility flags](#connection-visibility-flags) |
| sort_order | integer | The display order (0-2147483647) |

## Connection types

| Value | Name | Description |
| --- | --- | --- |
| bsky | BLUESKY | A Bluesky account authorized through atproto OAuth |
| domain | DOMAIN | A domain the account has proved it controls |

## Connection visibility flags

The flags decide which viewers see the connection on the owner's profile, using the same rule as the [profile field privacy flags](/http-api/users/#profile-field-privacy-flags). A new connection gets EVERYONE, and `0` hides it from every viewer. [List connections](#list-connections) ignores the flags.

| Value | Name | Description |
| --- | --- | --- |
| 1 << 0 | EVERYONE | Anyone who can view the profile |
| 1 << 1 | FRIENDS | Friends |
| 1 << 2 | MUTUAL_GUILDS | Members of a mutual guild |

## Connection verification object

[Initiate connection](#initiate-connection) returns this object.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| token | string | The value to publish at the domain as proof |
| type | string | [Connection type](#connection-types) |
| id | string | The domain being verified |
| instructions | string | Instructions for placing the token |
| initiation_token | string | The signed token for [Verify and create connection](#verify-and-create-connection), valid for 30 minutes |

## Domain ownership proof

Fluxer checks the proof once, when the connection is created. Use either method.

- Publish a TXT record at `_fluxer.<domain>` with the value `fluxer-verification=<token>`.
- Serve the token alone, without the prefix, at `https://<domain>/.well-known/fluxer-verification` with a 2xx status. Fluxer follows up to three HTTPS redirects to the same path on the domain with or without `www.`.

## Bluesky authorization object

[Start Bluesky authorization](#start-bluesky-authorization) returns this object.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| authorize_url | string | The URL to open for authorization |

## List connections

<RouteHeader method="GET" path="/v1/users/@me/connections" oauth2="connections" />

Returns every [connection object](#connection-object) the account has, in ascending `sort_order`.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[connection](#connection-object) object] | The connections were returned |
| 403 | [error response](/http-api/#error-response) | `MISSING_OAUTH_SCOPE` when the bearer lacks the `connections` scope |

The rate limit is 60 requests per minute, on the `connection:list` bucket.

## Initiate connection

<RouteHeader method="POST" path="/v1/users/@me/connections" />

Starts domain verification and returns a [connection verification object](#connection-verification-object), without creating a connection.

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| type | string | [Connection type](#connection-types), always `domain` |
| identifier | string | The domain to prove (1-253 characters) |
| visibility_flags? | integer | Ignored. Pass it to [Verify and create connection](#verify-and-create-connection) instead |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 201 | [connection verification](#connection-verification-object) object | Verification was started |
| 400 | [error response](/http-api/#error-response) | `BLUESKY_OAUTH_NOT_ENABLED` when the type is bsky |
| 403 | [error response](/http-api/#error-response) | `ACCOUNT_LIMITED` when the account is [limited](/http-api/users/#account-limitation) |
| 409 | [error response](/http-api/#error-response) | `CONNECTION_ALREADY_EXISTS` when the identifier is already linked |

The rate limit is 5 requests per minute, on the `connection:create` bucket.

## Verify and create connection

<RouteHeader method="POST" path="/v1/users/@me/connections/verify" />

Checks the [domain ownership proof](#domain-ownership-proof) and creates the connection. Fluxer sends [User Connections Update](/gateway/events/#user-connections-update).

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| initiation_token | string | The token from [Initiate connection](#initiate-connection) |
| visibility_flags? | integer | [Connection visibility flags](#connection-visibility-flags) (0-2147483647) |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 201 | [connection](#connection-object) object | The connection was created |
| 400 | [error response](/http-api/#error-response) | `CONNECTION_INITIATION_TOKEN_INVALID` when the token is invalid, expired or from another account |
| 403 | [error response](/http-api/#error-response) | `CONNECTION_VERIFICATION_FAILED` when the proof failed, or `ACCOUNT_LIMITED` |
| 409 | [error response](/http-api/#error-response) | `CONNECTION_ALREADY_EXISTS` when the domain is already linked, or `CONFLICT` on a concurrent change |

The rate limit is 5 requests per minute, on the `connection:verify_and_create` bucket.

## Update connection

<RouteHeader method="PATCH" path="/v1/users/@me/connections/{type}/{connection_id}" />

Updates the visibility or display order of a connection. Fluxer sends [User Connections Update](/gateway/events/#user-connections-update).

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| visibility_flags? | integer | [Connection visibility flags](#connection-visibility-flags) (0-2147483647) |
| sort_order? | integer | The new display order (0-2147483647) |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The connection was updated |
| 404 | [error response](/http-api/#error-response) | `CONNECTION_NOT_FOUND` when you have no such connection |
| 409 | [error response](/http-api/#error-response) | `CONFLICT` when the connection changed during the request |

The rate limit is 30 requests per minute, on the `connection:update` bucket.

## Delete connection

<RouteHeader method="DELETE" path="/v1/users/@me/connections/{type}/{connection_id}" />

Deletes a connection and sends [User Connections Update](/gateway/events/#user-connections-update). Deleting a bsky connection does not revoke Fluxer's access on Bluesky.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The connection was deleted |
| 404 | [error response](/http-api/#error-response) | `CONNECTION_NOT_FOUND` when you have no such connection |
| 409 | [error response](/http-api/#error-response) | `CONFLICT` when the connection list changed during the request |

The rate limit is 10 requests per minute, on the `connection:delete` bucket.

## Reorder connections

<RouteHeader method="PATCH" path="/v1/users/@me/connections/reorder" />

Sets each listed connection's `sort_order` to its position in the array. Unknown IDs are ignored and omitted connections keep their order. Fluxer sends [User Connections Update](/gateway/events/#user-connections-update).

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| connection_ids | array[string] | The connection IDs in their new order (1-20 entries) |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The connections were reordered |
| 409 | [error response](/http-api/#error-response) | `CONFLICT` when a connection changed during the request |

The rate limit is 30 requests per minute, on the `connection:update` bucket.

## Start Bluesky authorization

<RouteHeader method="POST" path="/v1/users/@me/connections/bluesky/authorize" />

Starts or renews a Bluesky connection. Send the user to `authorize_url`, and Bluesky then returns them through `/connections/bluesky/callback`, which clients never call directly.
### JSON body

| Field | Type | Description |
| --- | --- | --- |
| handle | string | Bluesky handle or profile URL (1-253 characters) |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | [Bluesky authorization](#bluesky-authorization-object) object | Authorization was started |
| 400 | [error response](/http-api/#error-response) | `BLUESKY_OAUTH_NOT_ENABLED` or `BLUESKY_OAUTH_AUTHORIZATION_FAILED` |
| 403 | [error response](/http-api/#error-response) | `ACCOUNT_LIMITED` when the account is [limited](/http-api/users/#account-limitation) |

After authorization, the browser ends on `/connection-callback` in the web app with `status=connected`, or with `status=error` and one of these `reason` values. Success creates or refreshes the connection and sends [User Connections Update](/gateway/events/#user-connections-update).

| Value | Description |
| --- | --- |
| not_enabled | Bluesky connections are not enabled on the instance |
| state_invalid | The authorization state is invalid |
| callback_failed | Authorization could not be completed |
| unknown | The connection could not be saved |

The rate limit is 5 requests per minute, on the `connection:create` bucket.

## Get Bluesky client metadata

<RouteHeader method="GET" path="/connections/bluesky/client-metadata.json" unauthenticated />

Returns the instance's atproto OAuth client metadata. Bluesky fetches this document during authorization, and it has to be publicly accessible.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | client metadata document | Bluesky connections are enabled |
| 404 | `{"error": "Bluesky OAuth is not enabled"}` | Bluesky connections are not enabled on the instance |

The rate limit is 60 requests per minute, on the `connection:bluesky:client_document` bucket.

## Get Bluesky JWKS

<RouteHeader method="GET" path="/connections/bluesky/jwks.json" unauthenticated />

Returns the instance's public OAuth signing keys as a JSON Web Key Set.

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | JSON Web Key Set | Bluesky connections are enabled |
| 404 | `{"error": "Bluesky OAuth is not enabled"}` | Bluesky connections are not enabled on the instance |

The rate limit is 60 requests per minute, on the `connection:bluesky:client_document` bucket.