Skip to content
Resenha API

Connections

A connection links an account to a verified domain, a Bluesky account or an account at a provider the instance set up. Visible connections appear in connected_accounts on the 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, which accepts a bearer with the connections scope.

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

A connection's type and id together identify it.

FieldTypeDescription
idstringThe ID of the connection, unique within its type
typestringConnection type
namestringThe domain, Bluesky handle or account name at the provider
verifiedbooleanWhether the connection is verified
visibility_flagsintegerConnection visibility flags
sort_orderintegerThe display order (0-2147483647)
provider_id?stringFor oauth, the provider's id. Null for other types, and while the instance has removed or turned off the provider
url?stringLink to the account or domain, or null when there is none

An oauth connection with a null provider_id is left out of profiles until the instance turns the provider back on.

ValueNameDescription
bskyBLUESKYA Bluesky account authorized through atproto OAuth
domainDOMAINA domain the account has proved it controls
oauthOAUTHAn account at an OAuth 2.0 or OpenID Connect provider the instance set up

The flags decide which viewers see the connection on the owner's profile, using the same rule as the profile field privacy flags. A new connection gets EVERYONE, and 0 hides it from every viewer. List connections ignores the flags.

ValueNameDescription
1 << 0EVERYONEAnyone who can view the profile
1 << 1FRIENDSFriends
1 << 2MUTUAL_GUILDSMembers of a mutual guild

Initiate connection returns this object.

FieldTypeDescription
tokenstringThe value to publish at the domain as proof
typestringConnection type
idstringThe domain being verified
instructionsstringInstructions for placing the token
initiation_tokenstringThe signed token for Verify and create connection, valid for 30 minutes

Resenha 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. Resenha follows up to three HTTPS redirects to the same path on the domain with or without www..

Start Bluesky authorization and Start provider authorization return this object.

FieldTypeDescription
authorize_urlstringThe URL to open for authorization
GET/v1/users/@me/connectionsconnections

Returns every connection object the account has, in ascending sort_order.

StatusBodyCondition
200array[connection object]The connections were returned
403error responseMISSING_OAUTH_SCOPE when the bearer lacks the connections scope

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

POST/v1/users/@me/connections

Starts domain verification and returns a connection verification object, without creating a connection.

FieldTypeDescription
typestringConnection type, always domain
identifierstringThe domain to prove (1-253 characters)
visibility_flags?integerIgnored. Pass it to Verify and create connection instead
StatusBodyCondition
201connection verification objectVerification was started
400error responseBLUESKY_OAUTH_NOT_ENABLED when the type is bsky, or CONNECTION_INVALID_TYPE when it is oauth
403error responseACCOUNT_LIMITED when the account is limited
409error responseCONNECTION_ALREADY_EXISTS when the identifier is already linked

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

POST/v1/users/@me/connections/verify

Checks the domain ownership proof and creates the connection. Resenha sends User Connections Update.

FieldTypeDescription
initiation_tokenstringThe token from Initiate connection
visibility_flags?integerConnection visibility flags (0-2147483647)
StatusBodyCondition
201connection objectThe connection was created
400error responseCONNECTION_INITIATION_TOKEN_INVALID when the token is invalid, expired or from another account
403error responseCONNECTION_VERIFICATION_FAILED when the proof failed, or ACCOUNT_LIMITED
409error responseCONNECTION_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.

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

Updates the visibility or display order of a connection. Resenha sends User Connections Update.

FieldTypeDescription
visibility_flags?integerConnection visibility flags (0-2147483647)
sort_order?integerThe new display order (0-2147483647)
StatusBodyCondition
204emptyThe connection was updated
404error responseCONNECTION_NOT_FOUND when you have no such connection
409error responseCONFLICT when the connection changed during the request

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

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

Deletes a connection and sends User Connections Update. Deleting a bsky connection does not revoke Resenha's access on Bluesky.

StatusBodyCondition
204emptyThe connection was deleted
404error responseCONNECTION_NOT_FOUND when you have no such connection
409error responseCONFLICT when the connection list changed during the request

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

PATCH/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. Resenha sends User Connections Update.

FieldTypeDescription
connection_idsarray[string]The connection IDs in their new order (1-20 entries)
StatusBodyCondition
204emptyThe connections were reordered
409error responseCONFLICT when a connection changed during the request

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

POST/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.

FieldTypeDescription
handlestringBluesky handle or profile URL (1-253 characters)
StatusBodyCondition
200Bluesky authorization objectAuthorization was started
400error responseBLUESKY_OAUTH_NOT_ENABLED or BLUESKY_OAUTH_AUTHORIZATION_FAILED
403error responseACCOUNT_LIMITED when the account is limited

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.

ValueDescription
not_enabledBluesky connections are not enabled on the instance
state_invalidThe authorization state is invalid
callback_failedAuthorization could not be completed
unknownThe connection could not be saved

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

POST/v1/users/@me/connections/oauth/{provider_id}/authorize

Starts or renews a connection to one of the connection_providers in the service availability object. Send the user to authorize_url, and the provider then returns them through /connections/oauth/{provider_id}/callback, which clients never call directly. The session that started the request has to still be signed in when the provider returns.

StatusBodyCondition
200Bluesky authorization objectAuthorization was started
400error responseCONNECTION_LIMIT_REACHED when the account has 20 connections
403error responseACCOUNT_LIMITED when the account is limited
404error responseUNKNOWN_CONNECTION_PROVIDER when the instance has no such provider turned on
503error responseSERVICE_UNAVAILABLE when the provider's discovery document can't be fetched

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 the connection, or refreshes its name when the account is already connected, and sends User Connections Update.

ValueDescription
not_enabledThe provider is not turned on
state_invalidThe authorization state is invalid, used or expired, or the session that started it signed out
deniedThe user did not allow the connection at the provider
callback_failedAuthorization could not be completed
already_connectedThe account is already connected
limit_reachedThe account has 20 connections
unknownThe connection could not be saved

The rate limit is 10 requests per minute, on the connection:oauth:authorize bucket.

GET/connections/bluesky/client-metadata.jsonUnauthenticated

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

StatusBodyCondition
200client metadata documentBluesky 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/connections/bluesky/jwks.jsonUnauthenticated

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

StatusBodyCondition
200JSON Web Key SetBluesky 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.