Conexões

Uma conexão vincula uma conta do Decoding Chat a um domínio verificado ou a uma conta Bluesky. Conexões visíveis aparecem em connected_accounts no objeto de perfil completo do usuário.

As rotas de conexão requerem token de usuário. Tokens de bot e bearers OAuth2 recebem 403 ACCESS_DENIED, exceto que Listar conexões aceita um bearer com o escopo connections. Contas com uma ação obrigatória pendente recebem 403 ACCOUNT_SUSPICIOUS_ACTIVITY. IDs de conexão não são snowflakes.

Metadados do cliente Bluesky e JWKS são públicos e não contêm dados de conta.

Limite de conexões da conta

Uma conta pode ter no máximo 20 conexões entre todos os tipos. Ultrapassar este limite retorna 400 CONNECTION_LIMIT_REACHED.

Iniciar conexão, Verificar e criar conexão e o callback do provedor que completa o fluxo de autorização Bluesky impõem o limite. Iniciar autorização Bluesky não impõe.

Objeto de conexão

O par de tipo e id identifica uma conexão. Ambos os valores aparecem no caminho de toda operação por conexão. Uma conexão só existe após seu prova externa ter sido bem-sucedida ao menos uma vez.

Estrutura

Campo	Tipo	Descrição
id¹	string	O ID da conexão, único dentro do seu tipo de conexão
type	string	Tipo de conexão
name²	string	O domínio ou handle Bluesky exibido para a conexão
verified³	boolean	Se a prova mais recente foi bem-sucedida
visibility_flags⁴	integer	Flags de visibilidade da conexão
sort_order⁵	integer	A ordem de exibição na lista de conexões da conta (0-2147483647)

¹ Um identificador domain tem 64 caracteres hexadecimais minúsculos e permanece o mesmo quando a conta recria aquela conexão de domínio. Um identificador bsky é um UUID atribuído na criação

² Para uma conexão domain, o nome é o domínio enviado. Para uma conexão bsky, é o handle Bluesky, atualizado ao completar o fluxo de autorização

³ O Decoding Chat o define como true quando a prova é bem-sucedida e novamente cada vez que uma autorização Bluesky é completada. Nenhuma verificação posterior o define como false

⁴ O valor armazenado é o inteiro fornecido pelo cliente e não é mascarado contra os bits definidos

⁵ Inicialmente o número de conexões existentes. Use Atualizar conexão ou Reordenar conexões para alterar

Tipos de conexão

Valor	Nome	Descrição
bsky¹	BLUESKY	Uma conta Bluesky autorizada por OAuth atproto
domain	DOMAIN	Um domínio que a conta provou que controla

¹ Use Iniciar autorização Bluesky. A rota de iniciação de domínio rejeita este tipo com 400 BLUESKY_OAUTH_NOT_ENABLED

Flags de visibilidade da conexão

As flags de uma conexão decidem quais visitantes do perfil do proprietário podem vê-la. O Decoding Chat as avalia contra um visitante com a mesma regra que as flags de privacidade de campo de perfil.

Valor	Nome	Descrição
1 << 0	EVERYONE	Qualquer pessoa com permissão para ver o perfil pode ver a conexão
1 << 1	FRIENDS	Amigos podem ver a conexão
1 << 2	MUTUAL_GUILDS	Membros de um servidor em comum podem ver a conexão

Uma conexão criada sem valor explícito recebe EVERYONE. Um valor 0 oculta a conexão de todos os visitantes, incluindo a leitura do próprio perfil pelo proprietário. Um cliente DEVE ignorar um bit que não reconheça.

Uma conexão não verificada nunca é exibida em um perfil, independentemente das flags. Um visitante sem permissão de ver o perfil completo não vê conexão alguma. Listar conexões ignora as flags e retorna todas as conexões que a conta possui.

Objeto de verificação de conexão

Retornado por Iniciar conexão. Nenhuma conexão existe até que Verificar e criar conexão seja bem-sucedido.

Estrutura

Campo	Tipo	Descrição
token¹	string	O valor a publicar no domínio como prova de propriedade
type	string	Tipo de conexão
id²	string	O domínio sendo verificado
instructions³	string	As instruções legíveis por humanos para publicar o token
initiation_token⁴	string	O token assinado aceito por Verificar e criar conexão

¹ O token tem 64 caracteres hexadecimais minúsculos. Repetir a operação para o mesmo destino retorna o mesmo token, portanto um cliente PODE manter um registro publicado entre tentativas

² O valor é o identifier exatamente como enviado, sem trimming, normalização de capitalização ou outro tipo de transformação

³ As instruções nomeiam tanto o registro DNS TXT quanto o caminho well-known descrito em Prova de propriedade de domínio

⁴ Uma credencial opaca que expira 30 minutos após a emissão e pode ser usada apenas pela conta iniciante

Prova de propriedade de domínio

Envie o domínio exatamente como deve ser verificado. Um domínio malformado pode passar pela iniciação, mas falhar na verificação de propriedade.

Publique um registro TXT em _fluxer.<domínio> cujo valor seja exatamente fluxer-verification=<token>. Se o registro tiver múltiplas strings, sua concatenação deve corresponder a esse valor. Aguarde a propagação das alterações DNS antes de verificar.

Como alternativa, sirva o token em https://<domínio>/.well-known/fluxer-verification. A resposta deve ter status 2xx e um corpo que corresponda ao token após remover espaços em branco. O corpo não pode exceder 16384 bytes. Até 5 redirecionamentos HTTP ou HTTPS são aceitos.

A URL HTTPS e cada redirecionamento devem usar um nome de domínio totalmente qualificado válido ou endereço IP público. Todos os endereços resolvidos devem ser publicamente acessíveis e permitidos pela política de URL de saída da instância. Redes privadas e reservadas não podem ser verificadas desta forma.

O Decoding Chat verifica a prova uma vez, na criação da conexão. Não há nova verificação posterior.

Objeto de autorização Bluesky

Retornado por Iniciar autorização Bluesky.

Estrutura

Campo	Tipo	Descrição
authorize_url	string	URL a abrir para autorização. Sua origem depende do `handle` enviado

Listar conexões

GET/v1/users/@me/connections

connections

Retorna todo objeto de conexão que a conta autenticada possui, em ordem ascendente de sort_order.¹ Uma conta sem conexões retorna um array vazio.

Um bearer sem connections recebe 403 MISSING_OAUTH_SCOPE.

¹ A ordenação é estável e não tem chave secundária, portanto duas conexões com o mesmo sort_order são retornadas na ordem armazenada, ascendente por tipo de conexão e depois descendente por id

Resposta

Status	Corpo	Condição
200	array[conexão object]	Coleção foi retornada, possivelmente como array vazio
403	resposta de erro	O token bearer não possui o escopo `connections` e a requisição retorna `MISSING_OAUTH_SCOPE`

Rate limit

60 requisições por minuto para cada usuário autenticado, no bucket connection:list.

Iniciar conexão

POST/v1/users/@me/connections

Inicia a verificação de propriedade de domínio e retorna um objeto de verificação de conexão. Esta operação não cria nenhuma conexão.

Apenas o tipo domain é aceito. Uma conexão Bluesky é criada por Iniciar autorização Bluesky.

Corpo JSON

Campo	Tipo	Descrição
type	string	Tipo de conexão, que deve ser domain
identifier	string	O domínio cuja propriedade se deve provar (1-253 caracteres)
visibility_flags?¹	integer	Flags de visibilidade da conexão (0-2147483647)

¹ Ignorado aqui. Defina a visibilidade em Verificar e criar conexão

Resposta

Status	Corpo	Condição
201	verificação de conexão object	A verificação foi iniciada
400	resposta de erro	O tipo solicitado é bsky e a requisição retorna `BLUESKY_OAUTH_NOT_ENABLED`
409	resposta de erro	Já existe uma conexão do mesmo tipo para aquele identificador (comparado sem distinção de maiúsculas) e a requisição retorna `CONNECTION_ALREADY_EXISTS`

Efeitos colaterais

Nenhum evento Gateway é emitido. Publique o token de verificação no domínio e chame Verificar e criar conexão antes que o token de iniciação expire.

Rate limit

5 requisições por minuto para cada usuário autenticado, no bucket connection:create, compartilhado com Iniciar autorização Bluesky.

Verificar e criar conexão

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

Verifica a prova de propriedade de domínio descrita por um token de iniciação assinado. Cria e retorna o objeto de conexão em caso de sucesso.

Use o token de iniciação retornado para este domínio e conta. O limite de conexões e as verificações de duplicidade ainda se aplicam quando a verificação for concluída.

Corpo JSON

Campo	Tipo	Descrição
initiation_token	string	O token de iniciação assinado retornado por Iniciar conexão
visibility_flags?¹	integer	Flags de visibilidade da conexão (0-2147483647)

¹ Um valor omitido armazena EVERYONE

Resposta

Status	Corpo	Condição
201	conexão object	A prova foi bem-sucedida e a conexão foi criada
400¹	resposta de erro	O token de iniciação não é utilizável e a requisição retorna `CONNECTION_INITIATION_TOKEN_INVALID`
403	resposta de erro	A prova falhou e a requisição retorna `CONNECTION_VERIFICATION_FAILED`
409	resposta de erro	O identificador já está vinculado (`CONNECTION_ALREADY_EXISTS`), ou a lista de conexões mudou durante a requisição (`CONFLICT`). Busque a lista antes de tentar novamente

¹ Tokens de iniciação inválidos, expirados ou de conta errada retornam o mesmo código

Efeitos colaterais

Sucesso cria a conexão e envia a lista completa para as sessões do chamador em User Connections Update. Uma prova com falha não cria conexão e não emite evento.

O token de iniciação permanece utilizável até expirar, portanto um chamador que publicou sua prova tarde pode tentar novamente com o mesmo token.

Rate limit

5 requisições por minuto para cada usuário autenticado, no bucket connection:verify_and_create.

Atualizar conexão

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

Atualiza a visibilidade ou a ordem de exibição de uma conexão existente e retorna 204 com corpo vazio. Omitir um campo deixa o valor armazenado inalterado.

Parâmetros de caminho

Campo	Tipo	Descrição
type	string	Tipo de conexão
connection_id	string	O ID da conexão, único dentro do seu tipo de conexão

Corpo JSON

Campo	Tipo	Descrição
visibility_flags?	integer	Flags de visibilidade da conexão (0-2147483647)
sort_order?	integer	A nova ordem de exibição (0-2147483647)

Resposta

Status	Corpo	Condição
204	vazio	A conexão foi atualizada
404¹	resposta de erro	Nenhuma conexão daquele tipo e identificador pertence ao chamador e a requisição retorna `CONNECTION_NOT_FOUND`
409	resposta de erro	A conexão mudou durante a requisição (`CONFLICT`). Busque-a novamente antes de tentar outra vez

¹ Ambos os parâmetros de caminho devem nomear a mesma conexão, portanto um identificador correto sob o tipo errado não corresponde

Efeitos colaterais

Envia a lista completa para as sessões do chamador em User Connections Update, mesmo que nenhum valor tenha mudado ou o corpo esteja vazio.

Atribuir um sort_order que outra conexão já possui é permitido. Listar conexões então resolve o empate pela ordem armazenada.

Rate limit

30 requisições por minuto para cada usuário autenticado, no bucket connection:update, compartilhado com Reordenar conexões.

Excluir conexão

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

Remove permanentemente uma conexão e retorna 204 com corpo vazio.

Parâmetros de caminho

Campo	Tipo	Descrição
type	string	Tipo de conexão
connection_id	string	O ID da conexão, único dentro do seu tipo de conexão

Resposta

Status	Corpo	Condição
204	vazio	A conexão foi excluída
404	resposta de erro	Nenhuma conexão daquele tipo e identificador pertence ao chamador e a requisição retorna `CONNECTION_NOT_FOUND`
409	resposta de erro	A conexão ou lista de conexões mudou durante a requisição (`CONFLICT`). Busque a lista antes de tentar novamente

Efeitos colaterais

Envia a lista restante para as sessões do chamador em User Connections Update. As outras conexões mantêm seus valores de sort_order.

Excluir uma conexão bsky a remove do Decoding Chat, mas não revoga a autorização no Bluesky.

Rate limit

10 requisições por minuto para cada usuário autenticado, no bucket connection:delete.

Reordenar conexões

PATCH/v1/users/@me/connections/reorder

Atribui a ordem de exibição das conexões listadas a partir de sua posição no array e retorna 204 com corpo vazio.

Corpo JSON

Campo	Tipo	Descrição
connection_ids¹ ²	array[string]	Os IDs de conexão em sua nova ordem de exibição (1-20 entradas)

¹ IDs desconhecidos são ignorados. Conexões omitidas mantêm sua ordem atual

² As conexões são combinadas apenas por id. Para IDs repetidos, a última posição vence

Resposta

Status	Corpo	Condição
204	vazio	As conexões foram reordenadas
409	resposta de erro	Uma conexão mudou durante a requisição (`CONFLICT`). Busque a lista novamente antes de tentar outra vez

Efeitos colaterais

Cada conexão nomeada recebe seu índice baseado em zero no array como sort_order. A lista completa é enviada para as sessões do chamador em User Connections Update, mesmo que a ordem não tenha mudado.

A reordenação é atômica. Uma requisição que retorna 409 CONFLICT não altera nenhuma ordem e não emite nenhum evento. Quando o Decoding Chat salva a ordem e depois falha ao enviar User Connections Update, a requisição retorna erro mas a nova ordem permanece salva.

Um array parcial pode deixar duas conexões com o mesmo sort_order, que Listar conexões resolve pela ordem armazenada.

Rate limit

30 requisições por minuto para cada usuário autenticado, no bucket connection:update, compartilhado com Atualizar conexão.

Iniciar autorização Bluesky

POST/v1/users/@me/connections/bluesky/authorize

Inicia ou renova uma conexão Bluesky. O Bluesky deve estar habilitado na instância. Use este fluxo novamente quando a autorização expirar ou a conexão precisar de reautorização.

Corpo JSON

Campo	Tipo	Descrição
handle	string	Handle Bluesky ou URL de perfil (1-253 caracteres)

Resposta

Status	Corpo	Condição
200	autorização Bluesky object	Envie o usuário para `authorize_url`
400	resposta de erro	Indisponível (`BLUESKY_OAUTH_NOT_ENABLED`) ou falhou (`BLUESKY_OAUTH_AUTHORIZATION_FAILED`)

Completando o fluxo

Envie o usuário para authorize_url. O Bluesky o retorna por /connections/bluesky/callback. Os clientes não devem chamar essa rota diretamente.

O navegador então chega em /connection-callback no aplicativo web com status=connected, ou status=error e um destes motivos:

Valor	Descrição
not_enabled	Conexões Bluesky estão indisponíveis
state_invalid	Estado de autorização inválido. Inicie um novo fluxo
callback_failed	A autorização não pôde ser concluída. Inicie um novo fluxo
unknown	A conexão não pôde ser salva

Sucesso cria ou atualiza a conexão verificada e publica User Connections Update. Completar o fluxo novamente também atualiza o handle Bluesky exibido.

Rate limit

5 requisições por minuto para cada usuário autenticado, no bucket connection:create, compartilhado com Iniciar conexão.

Obter metadados do cliente Bluesky

GET/connections/bluesky/client-metadata.json

Unauthenticated

Retorna os metadados do cliente OAuth atproto da instância como JSON. Este endpoint deve ser publicamente acessível para autorização Bluesky.

Resposta

Status	Corpo	Condição
200	documento de metadados do cliente	O Bluesky está configurado
404	`{"error": "Bluesky OAuth is not enabled"}`	O Bluesky está indisponível

Rate limit

60 requisições por minuto para cada endereço IP do cliente, no bucket connection:bluesky:client_document, compartilhado com Obter JWKS Bluesky.

Obter JWKS Bluesky

GET/connections/bluesky/jwks.json

Unauthenticated

Retorna as chaves públicas de assinatura OAuth da instância como um JSON Web Key Set. Este endpoint deve ser publicamente acessível para autorização Bluesky.

Resposta

Status	Corpo	Condição
200	JSON Web Key Set	O Bluesky está configurado
404	`{"error": "Bluesky OAuth is not enabled"}`	O Bluesky está indisponível

Rate limit

60 requisições por minuto para cada endereço IP do cliente, no bucket connection:bluesky:client_document, compartilhado com Obter metadados do cliente Bluesky.