Connections¶

A connection links a TEBHOS account to something outside TEBHOS: a domain the user has proved they control, or an account on a supported external service. Verified connections that the viewer is allowed to see appear in connected_accounts on the user's profile (see Users).

Every /users/@me/connections route requires a user session token, except that List connections also accepts an OAuth2 access token with the connections scope. A valid bot token is rejected with 403 ACCESS_DENIED (an invalid one with 401), and so is a valid access token on any other connection route. Connection IDs are strings, not snowflakes.

Account connection limit¶

An account can hold at most 20 connections across all types. Creating one more returns 400 BAD_REQUEST.

Connection object¶

A connection is identified by the pair of its type and id. Both appear in the path of every per-connection route.

Structure¶

Example¶

{
  "id": "12345678",
  "type": "github",
  "name": "partyparrot",
  "verified": true,
  "visibility_flags": 1,
  "sort_order": 0
}

Connection types¶

A provider type is usable only when the instance has credentials for it. List connection providers reports which ones are enabled. Steam uses OpenID and is always enabled.

Connection visibility flags¶

The flags decide which viewers of the owner's profile see a connection.

A new connection gets EVERYONE (1) unless the request sets another value. A value of 0 hides the connection from everyone, including the owner's view of their own profile. An unverified connection never appears on a profile, whatever its flags. List connections ignores the flags and returns every connection the account holds.

Connection verification object¶

Returned by Initiate connection. No connection exists until Verify and create connection succeeds.

Structure¶

The proof token depends only on the account and the lowercased domain, so repeating Initiate connection for the same domain returns the same token, and a published record can stay in place across attempts.

Domain ownership proof¶

Publish the token in one of two ways:

• DNS: a TXT record at _tebhos.<domain> whose value is exactly tebhos-verification=<token>. TEBHOS resolves the record over DNS-over-HTTPS, so allow time for DNS changes to propagate before verifying.
• HTTPS: serve the bare token at https://<domain>/.well-known/tebhos-verification. The response must have a 2xx status and a body of at most 4096 bytes that equals the token after trimming whitespace. Redirects are not followed, and the request times out after 5 seconds.

The domain must contain a . and only ASCII letters, digits, ., and -. Any other value fails the proof.

List connections¶

GET /users/@me/connections

Returns an array of every connection object the account holds, sorted by sort_order. An account with no connections receives an empty array.

Also accepts an OAuth2 access token with the connections scope; a token without it receives 403 MISSING_OAUTH_SCOPE.

Rate limit¶

60 requests per minute for each account, on the connection:list bucket.

List connection providers¶

GET /users/@me/connections/providers

Returns the provider connection types and whether each is enabled on this instance.

Response¶

Initiate connection¶

POST /users/@me/connections

Starts domain ownership verification and returns a connection verification object. No connection is created yet.

JSON body¶

Response¶

Rate limit¶

5 requests per minute for each account, on the connection:create bucket.

Verify and create connection¶

POST /users/@me/connections/verify

Checks the domain ownership proof for an initiation token, and on success creates and returns the connection object with status 201.

JSON body¶

Response¶

The initiation token stays usable until it expires, so a client whose proof was not yet visible can retry with the same token.

Side effects¶

Success sends the complete, sorted list to the account's sessions in a USER_CONNECTIONS_UPDATE Gateway event with the payload {"connections": [...]}.

Rate limit¶

5 requests per minute for each account, on the connection:verify_and_create bucket.

Re-verify a connection¶

POST /users/@me/connections/{type}/{connection_id}/verify

Runs the ownership proof of an existing domain connection again. Returns the updated connection object on success.

Path parameters¶

Response¶

A failed proof marks a previously verified connection as unverified, which removes it from the profile. A background task that re-checks an account's verified domain connections can do the same.

Rate limit¶

5 requests per minute for each account, on the connection:verify bucket.

Update connection¶

PATCH /users/@me/connections/{type}/{connection_id}

Updates the visibility or position of one connection. An omitted field is left unchanged. Returns the updated connection object.

Path parameters¶

JSON body¶

Both path parameters must name the same connection: a correct ID under the wrong type returns 404. Two connections may share a sort_order.

Response¶

Side effects¶

Sends the complete list in USER_CONNECTIONS_UPDATE.

Rate limit¶

30 requests per minute for each account, on the connection:update bucket, shared with Reorder connections.

Delete connection¶

DELETE /users/@me/connections/{type}/{connection_id}

Removes one connection. Returns 204.

Path parameters¶

Response¶

Deletion is immediate and cannot be undone. Other connections keep their sort_order. Deleting a provider connection does not revoke anything on the external service.

Side effects¶

Sends the remaining list in USER_CONNECTIONS_UPDATE.

Rate limit¶

10 requests per minute for each account, on the connection:delete bucket.

Reorder connections¶

PATCH /users/@me/connections/reorder

Sets the display order of the listed connections from their position in the array. Returns 204.

JSON body¶

Each listed connection gets its zero-based array index as sort_order. Unknown IDs are ignored, and connections that are not listed keep their current value, so a partial list can leave two connections sharing a position.

Side effects¶

Sends the complete list in USER_CONNECTIONS_UPDATE, even when nothing changed.

Rate limit¶

30 requests per minute for each account, on the connection:update bucket, shared with Update connection.

Start provider authorisation¶

POST /users/@me/connections/{provider}/authorize

Starts linking an external account. Returns {"authorize_url": string}; open that URL in a browser window (TEBHOS opens a pop-up).

Path parameters¶

Response¶

Completing the flow¶

The external service returns the browser to GET /connections/{provider}/callback on the API. Clients do not call that route themselves. It answers with a small HTML page that reports the result and closes the window after a moment.

The authorisation state is valid for ten minutes and can be completed once. Spotify and X use PKCE.

On success, TEBHOS creates a verified connection whose id is the account ID on the external service and whose name is its display name, with visibility EVERYONE, and sends USER_CONNECTIONS_UPDATE. Linking the same external account again refreshes its name and verification time instead of creating a duplicate. The page reports a failure when the user cancelled, the state expired, the exchange failed, or the account already has 20 connections.

Bluesky routes¶

These routes exist so that clients built for Bluesky connections receive a clear answer. Bluesky is not enabled on TEBHOS.