defineConnectionProvider({ type: 'oauth', ... }) não precisarão migrar.
defineConnectionProvider
Declare como as conexões do seu app são obtidas
defineConnectionProvider
Declare como as conexões do seu app são obtidas
Um provedor de conexão descreve o handshake OAuth de que seu app precisa. O usuário clica em “Adicionar conexão” nas configurações do seu app, conclui a tela de consentimento do provedor e uma linha Pontos-chave:
ConnectedAccount é criada no seu workspace.Uma configuração funcional precisa de dois arquivos — o provedor de conexão e uma declaração correspondente de serverVariables em defineApplication que contém as credenciais do cliente OAuth.src/connection-providers/linear-connection.ts
src/application.config.ts
nameé a string de identificador exclusivo usada emlistConnections({ providerName })(kebab-case, deve corresponder a^[a-z][a-z0-9-]*$).displayNameaparece na aba de configurações do app e na lista de ferramentas de IA.clientIdVariable/clientSecretVariablesão nomes, não valores — devem corresponder às chaves declaradas emdefineApplication.serverVariables. Osclient_ideclient_secretreais são inseridos pelo administrador do servidor por meio da interface de registro do app e nunca são versionados no seu repositório.- Use
serverVariables(nãoapplicationVariables) — as credenciais OAuth são do servidor como um todo e há um app OAuth por servidor do Twenty. - Até que ambos os
serverVariablessejam preenchidos, a aba de configurações do app mostra uma dica “precisa de administrador do servidor” e o botão “Adicionar conexão” fica desativado. type: 'oauth'é o único valor compatível atualmente. O discriminador é compatível com versões futuras: tipos futuros ('pat','api-key', …) adicionarão novos blocos de subconfiguração ao lado deoauth.
listConnections / getConnection
Use conexões a partir de uma função de lógica
listConnections / getConnection
Use conexões a partir de uma função de lógica
Dentro de um handler de função de lógica, Cada conexão tem:
Pontos-chave:
listConnections({ providerName }) retorna as linhas ConnectedAccount deste app para o provedor fornecido, com tokens de acesso atualizados.src/logic-functions/handlers/create-linear-issue-handler.ts
| Campo | Descrição |
|---|---|
id | ID de linha exclusivo; passe para getConnection(id) para buscar novamente um único registro |
visibility | 'user' (privada para um membro do workspace) ou 'workspace' (compartilhada com todos os membros) |
scopes | Permissões OAuth concedidas pelo provedor de origem (distintas de visibility — não têm relação) |
userWorkspaceId | O id de userWorkspace do proprietário — útil para selecionar “a conexão do usuário da requisição” em gatilhos de rota HTTP |
accessToken | Token de acesso OAuth recente (atualizado automaticamente se estiver expirado) |
name / handle | O nome de exibição da conexão (derivado automaticamente no callback do OAuth, renomeável pelo usuário) |
authFailedAt | Definido quando a atualização mais recente falhou; o usuário deve reconectar |
- Passe
{ providerName }para filtrar por provedor; omita para obter todas as conexões que este app possui em todos os provedores. - O servidor atualiza transparentemente o token de acesso antes de retornar. Seu handler sempre vê um token utilizável (ou
authFailedAtdefinido). getConnection(id)é o equivalente de uma única linha.
Visibilidade por usuário vs. compartilhada no workspace
Como os usuários escolhem entre credenciais privadas e compartilhadas
Visibilidade por usuário vs. compartilhada no workspace
Como os usuários escolhem entre credenciais privadas e compartilhadas
Quando um usuário clica em “Adicionar conexão”, é solicitado que escolha uma visibilidade:Várias conexões por (usuário, provedor) são permitidas, então o mesmo usuário pode manter “Linear pessoal” e “Linear de trabalho” lado a lado.
- Apenas para mim — a credencial é privada para o usuário que a conectou. Qualquer função de lógica chamada em seu nome (gatilho de rota HTTP com
isAuthRequired: true) a vê; gatilhos cron e eventos de banco de dados não. - Compartilhada no workspace — qualquer membro do workspace pode usar a credencial. Gatilhos de cron / banco de dados também a veem, pois não há um usuário da requisição.
Configuração única do provedor
Registre seu app OAuth no serviço de terceiros
Configuração única do provedor
Registre seu app OAuth no serviço de terceiros
Para cada provedor de conexão, o administrador do servidor precisa primeiro registrar um app OAuth no serviço de terceiros.
- Acesse as configurações de desenvolvedor do provedor (por exemplo, https://linear.app/settings/api/applications/new).
- Defina a URI de redirecionamento como
\<SERVER_URL>/auth/apps/callback. - Copie o ID do cliente e o Segredo do cliente gerados.
- Abra o app instalado no Twenty como administrador do servidor → defina os valores nos
serverVariablescorrespondentes. - Os membros do workspace podem então adicionar conexões na seção Conexões de cada app.