Quando um sistema de negócio remoto se conecta à plataforma, a parte difícil raramente é a chamada de API em si. É decidir quem guarda cada credencial, por quanto tempo ela vale e em quanto tempo uma associação revogada passa a valer. Essas três perguntas determinam se o sistema continuará se comportando bem meses depois. Isto é o que sustentamos nesse caminho e onde ficam os limites.

Dois níveis de credencial, e a de longa duração não sai do servidor

A plataforma emite dois tipos de identidade. A identidade de serviço de módulo é de longa duração, fica apenas no servidor do sistema de negócio e serve para trocar um Launch Grant (POST /integration/v1/sso/launch-grants/exchange) e solicitar um token de serviço de instância (POST /integration/v1/service-tokens). O token de serviço de instância é de curta duração: cinco minutos no máximo, audience fixa e escopos restritos à requisição em andamento, devolvido com no-store.

O navegador, portanto, nunca recebe credenciais de módulo. O frontend apenas entrega o código de lançamento recebido ao próprio backend, e toda troca acontece no servidor. Para tokens de curta duração, o SDK mantém cache por instância e conjunto de escopos solicitado, por no máximo 300 segundos, sem Refresh: solicita um novo quando o tempo restante cai abaixo de uma janela de segurança, uma rajada simultânea provoca uma única troca, e tokens nunca são reutilizados entre instâncias.

O Launch é uma troca de uso único que termina na sua própria sessão

Quem chega da plataforma traz um código de lançamento, não uma credencial de longa duração. O backend troca e consome o Grant com a identidade de serviço de módulo e, em seguida, estabelece a sessão local do sistema de negócio. Essa sessão guarda apenas identidade derivada: nem token da plataforma, nem código de lançamento, nem Client Secret, nem claims completas.

Tanto a troca quanto as verificações posteriores de sessão validam assinaturas: o JWKS de execução da plataforma confere algoritmo, emissor, audience, validade, token_use, conta e instância de aplicação, além dos escopos, com uma origem de chaves que recusa redirecionamentos e limita o tamanho da resposta. Há um ponto que se confunde facilmente: a página de acesso dizer "conectado" prova apenas que o backend consegue ler as chaves públicas. Não prova que o visitante está autenticado nem que o caminho de Launch funciona. Mantenha essas três afirmações separadas.

Quando uma associação é revogada, a sessão local precisa convergir

Uma sessão válida na plataforma não significa que a sessão local possa durar indefinidamente. Ao longo de uma sessão longa, um membro removido, um papel alterado ou uma instância suspensa precisam chegar ao sistema de negócio dentro de uma janela limitada. O mecanismo é uma verificação em lote com a identidade de serviço de instância (POST /integration/v1/session-checks): active é verdadeiro apenas quando instância, associação de instância, conta e associação de conta são válidas ao mesmo tempo, enquanto não membros e usuários desconhecidos retornam active=false, de modo que a existência da associação não vaza. Cada sistema converge na janela que declara e, na prática, a janela de escrita pode ser mais curta que a de leitura.

Se os escopos não cobrirem, falhe localmente

Toda requisição de execução carrega escopos. O SDK só devolve credenciais utilizáveis quando os escopos realmente concedidos cobrem aquela requisição; caso contrário, falha localmente e não envia nenhuma requisição de negócio. O valor dessa regra é separar "a plataforma não autorizou" de "a chamada à plataforma falhou": o primeiro é um problema de configuração que deve ficar visível de imediato, em vez de virar um erro opaco do fornecedor.

Idempotência e novas tentativas são do chamador

O SDK nunca repete uma requisição por conta própria. Operações de escrita precisam de uma chave de idempotência estável fornecida pelo chamador, e uma requisição falha não é reenviada — porque "resultado desconhecido" e "falha" são estados diferentes, e só o sistema de negócio sabe se deve reenviar, consultar ou avisar o usuário. Quanto a erros, os Problem Details da plataforma são mapeados para classes estáveis (não autenticado, proibido, conflito, limite de taxa, erro de servidor e outras) com marca de nova tentativa possível, e credenciais e corpos de resposta nunca chegam aos logs nem à serialização de erros.

Dois artefatos, dois caminhos de obtenção

Os dois SDKs não têm a mesma disponibilidade, então confirme primeiro qual se aplica. No TypeScript e Node o pacote é @td-runlume/platform-integration-sdk no npm público, Apache-2.0, para uso no servidor. No Java a coordenada é app.runlume.platform:platform-integration-sdk-java, servida pelo repositório Nexus da plataforma e ausente do Maven Central; o uso depende das credenciais e da licença concedidas pela plataforma, e os artefatos não podem ser redistribuídos. Integrações Java costumam combiná-lo com o starter do Spring Boot, que monta os componentes do SDK e a cadeia de validade da sessão local, deixando ao sistema de negócio dois pontos de extensão: a fronteira de sessão e a leitura do workspace.

Os caminhos de endpoint, os nomes de escopo e as capacidades disponíveis seguem o contrato e a documentação acordados no onboarding. Este artigo cobre apenas os limites que o servidor precisa sustentar; as capacidades em si começam em capacidades da plataforma.