Entrar com Vimine

Os associados de uma associação entram no seu site com a conta Vimine deles e autorizam você, com um consentimento explícito, a usar alguns dos seus dados. É OAuth 2.1 com PKCE: a senha só é digitada na página do Vimine, nunca na sua; o seu site recebe tokens limitados às permissões concedidas.

Antes de começar

Você precisa de um cliente Site ou App nativo com o seu redirect_uri registrado — veja Registrar um cliente — e do SDK instalado (Instalar o SDK). Para desenvolver sem tocar em dados reais, use um cliente de teste e o sandbox.

O fluxo

1. A partir de um clique do associado, o seu site manda o navegador (a janela principal, nunca um iframe) para a página de autorização:

   https://app.vimine.network/authorize
       ?client_id=vmc_…&redirect_uri=https://www.example.org/vimine/callback
       &response_type=code&state=…&code_challenge=…&code_challenge_method=S256
       &scope=profile:read%20membership:read

2. O associado entra (se ainda não tiver entrado) e vê quem está recebendo o quê. Ele confirma ou cancela.
3. O Vimine manda o navegador de volta para o seu redirect_uri com code e state (ou error=access_denied).
4. O seu site troca o código em POST https://api.vimine.network/v1/oauth/token (grant_type=authorization_code, code, code_verifier, client_id, redirect_uri) e recebe um access token (10 minutos) e um refresh token (rotativo; 30 dias, 14 de inatividade).

O SDK faz tudo isso por você.

Com o SDK

qualquer página

import { Vimine } from '@vimine/sdk';

const vimine = new Vimine({
    clientId: 'vmc_…',
    redirectUri: 'https://www.example.org/vimine/callback',
    scopes: ['profile:read', 'membership:read']
});

// a partir de um clique: `returnTo` é um estado seu, você o recebe de volta depois do callback
document.querySelector('#sign-in').addEventListener('click', () => vimine.signIn({ returnTo: location.pathname }));

página de callback

const result = await vimine.handleRedirect();   // null quando a URL não traz parâmetros de login
if (result) location.replace(result.returnTo || '/');

Opções de signIn():

Opção	Efeito
scopes	as permissões a pedir neste login (padrão: as do construtor, ou profile:read membership:read)
prompt: 'login'	força o formulário de credenciais mesmo com uma sessão Vimine ativa
prompt: 'consent'	mostra sempre a tela de consentimento
returnTo	um estado seu (por exemplo, a página de onde o associado partiu), guardado localmente e devolvido por handleRedirect()

handleRedirect() lança um VimineError com code access_denied quando o associado cancelou, state_mismatch ou no_flow quando o retorno não corresponde a um login iniciado neste navegador.

A sessão

• Os tokens ficam no sessionStorage (por aba). storage: 'local' os compartilha entre as abas e sincroniza o logout; 'memory' nunca os persiste. Você pode passar um adaptador seu.
• vimine.getAccessToken() renova sozinho 30 segundos antes do vencimento; uma chamada que recebe 401 é repetida uma vez depois da renovação. Um refresh token reutilizado (um copiado, por exemplo) revoga toda a família de sessões.
• vimine.onChange(session => …) avisa sobre login, renovação e logout.
• vimine.getSession().sub é o identificador do associado para a sua associação (vms_…): estável no tempo, diferente em cada associação, nunca um id interno.

O que você pode pedir

await vimine.me.get();                                     // profile:read
await vimine.me.update({ phone: '+39 …' });                // profile:write
await vimine.membership.get();                             // membership:read — status, verdict, expires_at, statuto, card
await vimine.membership.events({ limit: 20 });             // histórico de status
await vimine.membership.statuto();                         // o statuto em vigor e se o associado o aceitou
await vimine.membership.acceptStatuto({ version: 3 });     // statuto:accept
await vimine.membership.request({ accept_statuto: { version: 3 }, privacy_notice: { version: 2 } });   // membership:request → carteirinha pendente
await vimine.membership.card();                            // o token da carteirinha (QR) e a sua janela
await vimine.legal.acceptances();                          // legal:read → o que a pessoa aceitou e o que ainda está pendente
await vimine.legal.record({ kind: 'privacy_notice', version: 2 });   // legal:accept → ciência do aviso da associação
await vimine.connections.list();  await vimine.connections.revoke('vmc_…');

Documentos jurídicos

legal.acceptances() lista as aceitações da pessoa e, em pending, os documentos ainda a confirmar na sua versão em vigor: as condições de uso da conta e o aviso de privacidade da plataforma (platform), o aviso desta associação aos associados (privacy_notice). Mostre o texto (GET /v1/legal/{kind}, GET /v1/aps/{slug}/privacy-notice) e registre a confirmação com legal.record(): a versão precisa ser a que está em vigor, senão 422 <kind>_outdated.

Ativação

O que acontece com um pedido (membership.request()) depende de como a associação admite os seus associados — admission no perfil público, explicado em Admissão e ativação. Se quem decide é a diretoria, ele fica pending com pending_reasons ordenados (approval, depois payment) e a taxa só é paga depois da admissão (payment_open); caso contrário, ele já nasce ativo quando o tipo é gratuito, ou quando a taxa é registrada. Uma carteirinha ativa pode trazer um valid_from no futuro: a carteirinha vale na entrada a partir daí. Mostre ao associado quota e payment_instructions sempre que payment estiver presente.

verdict é o que conta na entrada: valid, expired, statuto_required (nova aceitação atrasada) ou inactive. Quem ainda não é associado também pode entrar e usar membership.request: o consentimento às permissões de adesão também é permitido a quem não é associado; as outras permissões exigem uma carteirinha naquela associação.

Cada método está detalhado em Vimine; as respostas, em Tipos.

O logout

await vimine.signOut();                        // revoga a sessão da API e a esquece
await vimine.signOut({ everywhere: true });    // também encerra a sessão Vimine do associado e volta para o seu site

Com everywhere, o navegador passa por https://app.vimine.network/oauth/logout?client_id=…&post_logout_redirect_uri=…; o endereço de retorno precisa estar numa origem registrada para o cliente. Quando o associado sai do Vimine, todas as sessões de API dos apps dele são revogadas (single sign-out); o mesmo acontece quando ele revoga um app em Apps conectados ou redefine a senha.

Sem o SDK

Se você não pode usar o SDK (outra linguagem, uma plataforma low-code), o fluxo é OAuth 2.1 padrão.

Autorização — GET https://app.vimine.network/authorize

Parâmetro
client_id	o seu vmc_…
redirect_uri	um dos registrados, idêntico
response_type	code
state	valor aleatório, para comparar no retorno
code_challenge, code_challenge_method	PKCE, só S256
scope	permissões separadas por espaço
prompt	opcional: login, consent
ui_locales	opcional: um dos idiomas do Vimine — it (padrão), en, zh-Hans, zh-Hant, fr, es, de, pt-BR

Troca — POST https://api.vimine.network/v1/oauth/token, corpo application/x-www-form-urlencoded:

grant_type=authorization_code&code=…&code_verifier=…&client_id=vmc_…&redirect_uri=…

resposta

{ "access_token": "…", "token_type": "Bearer", "expires_in": 600, "refresh_token": "…",
  "scope": "profile:read membership:read", "sub": "vms_…" }

Renovação — o mesmo endpoint com grant_type=refresh_token&refresh_token=…&client_id=…: a resposta traz um novo refresh token (o antigo continua válido por 15 segundos para as requisições concorrentes; depois, reutilizá-lo revoga toda a família).

Revogação — POST /v1/oauth/revoke com token=…&token_type_hint=refresh_token (RFC 7009).

Descoberta — GET https://api.vimine.network/.well-known/oauth-authorization-server (RFC 8414) lista endpoints, escopos e métodos suportados.

Os erros desses endpoints usam o formato OAuth: { "error": "invalid_grant", "error_description": "…" }.