API de links de conviteCopy Anchor Link

Use estas rotas para convidar uma pessoa sem informar o e-mail dela. Quem tem permissão gera um link de uso único que expira em 24 horas; quem recebe o link consulta a organização e o papel e cria uma conta vinculada somente àquela organização. Para o passo a passo no console, veja Convidar membros.

Autenticação e autorizaçãoCopy Anchor Link

As rotas de gestão (gerar, listar e revogar) exigem uma sessão de usuário válida e a permissão member.invite em organization:*. Chaves de API não são aceitas. Informe a organização ativa no header x-organization-id, com o mesmo valor do :id da rota.

Authorization: Bearer <user-token>
x-organization-id: <organization-id>
Content-Type: application/json

O owner tem acesso completo. Um assistant com member.invite só gera links para o papel member e só concede permissões e políticas que ele mesmo possui; tentar conceder mais responde 403.

As rotas de consulta e aceite do link são públicas: o próprio token do link é a credencial.

URL base e rotasCopy Anchor Link

https://api.zenifra.com/v1

Gerar um linkCopy Anchor Link

POST /v1/organizations/:id/invite-links

{
  "role": "member",
  "policy_ids": ["<policy-id>"]
}

Resposta 201:

{
  "status": "success",
  "message": "organization invite link created with success",
  "data": {
    "id": "<link-id>",
    "token": "<token>",
    "role": "member",
    "policy_ids": ["<policy-id>"],
    "expires_at": "2026-10-27T12:00:00.000Z",
    "created_at": "2026-10-26T12:00:00.000Z"
  }
}

O link para compartilhar é https://console.zenifra.com/invite/<token>. O token aparece somente nesta resposta: guarde-o ou compartilhe-o na hora. Depois disso, só é possível listar ou revogar o link.

Erros: 400 para dados inválidos, 403 para permissão insuficiente (inclusive tentar conceder mais do que você tem) e 404 quando uma política não é encontrada. Limite: 10 requisições por minuto.

Listar links ativosCopy Anchor Link

GET /v1/organizations/:id/invite-links

Retorna os links ainda não usados, revogados nem expirados, do mais recente para o mais antigo. O token não é retornado.

{
  "status": "success",
  "message": "get organization invite links with success",
  "data": [
    {
      "id": "<link-id>",
      "role": "member",
      "policy_ids": ["<policy-id>"],
      "expires_at": "2026-10-27T12:00:00.000Z",
      "created_at": "2026-10-26T12:00:00.000Z"
    }
  ]
}

Limite: 30 requisições por minuto.

Revogar um linkCopy Anchor Link

DELETE /v1/organizations/:id/invite-links/:linkId

Responde 200 com status: "success". Depois de revogado, o link passa a responder como indisponível. Se o link não existe, já foi usado ou expirou, a resposta é 404 com a mensagem invite link not found. Limite: 10 requisições por minuto.

Consultar um linkCopy Anchor Link

GET /v1/organizations/invite-links/:token

Rota pública. Retorna o nome da organização e o papel, para exibir antes do cadastro.

{
  "status": "success",
  "message": "get organization invite link with success",
  "data": {
    "organization": { "name": "Minha empresa" },
    "role": "member",
    "expires_at": "2026-10-27T12:00:00.000Z"
  }
}

Links usados, revogados ou expirados respondem 404 com a mensagem invite link not found. Limite: 30 requisições por minuto.

Aceitar um link e criar a contaCopy Anchor Link

POST /v1/organizations/invite-links/:token/accept

Rota pública. Cria uma conta que pertence somente à organização do link, informando apenas dados básicos.

{
  "name": "Maria Silva",
  "email": "[email protected]",
  "password": "<senha>",
  "accepted_terms": true,
  "accepted_age": true,
  "preferred_locale": "pt-BR"
}

Não são exigidos CPF/CNPJ, telefone, data de nascimento nem endereço. A resposta 201 tem o mesmo formato do cadastro normal: token de sessão e challenge_token, usado para confirmar o e-mail com o código enviado.

{
  "status": "success",
  "message": "create user with success",
  "data": {
    "token": "<session-token>",
    "challenge_token": "<challenge-token>"
  }
}

A conta criada:

• tem acesso somente à organização do link, com o papel, as políticas e as permissões definidos na geração;
• não recebe organização própria nem crédito de cadastro;
• não recebe convites de outras organizações nem sugestão de entrada por domínio de e-mail;
• perde o acesso se for removida da organização.

O link é consumido no aceite e não pode ser reutilizado.

Erros: 400 para dados inválidos, 404 quando o link está indisponível (invite link not found) e 409 com user already exists quando o e-mail já tem conta na Zenifra; nesse caso, envie um convite por e-mail. Limite: 5 criações de conta por minuto.