Nevolus IA – API de Autenticação Remota

Índice

Visão Geral

Esta API permite que sistemas externos autentiquem usuários com o perfil “remote-login” de forma transparente para acesso aos chatbots, sem expor senhas, utilizando um fluxo baseado em token de uso único. Há duas formas de autenticação disponíveis:

Login via browser: O usuário é redirecionado para a Nevolus, que realiza o login e o redireciona para a página desejada.
Login transparente (backend): O sistema externo autentica o usuário e injeta os cookies de sessão no navegador do usuário.

A criação dos usuários com perfil “remote-login” pode ser feita via interface web (individualmente pelo menu: “Usuários” ou em lote pelo menu “Importar Usuários”). Alternativamente, fornecemos endpoints para criação e exclusão de contas de usuários.

Endpoint

POST /wp-json/custom/v1/generate-login-token

Headers obrigatórios

Header	Valor
Authorization	Bearer API_KEY
Content-Type	application/json
Accept	application/json

Body (JSON)

{
  "username": "NOME_DO_USUARIO"
}

Resposta de Sucesso (200)

{
  "login_token": "TOKEN_GERADO",
  "expires": nnnnnnnnnn,
  "login_url": "https://sua_url_nevolus/custom-login?token=TOKEN_GERADO"
}

login_token: Token de uso único válido por 5 minutos.
expires: Timestamp de expiração do token.
login_url: URL para login via browser (pode ser complementada com o parâmetro redirect).

Erros comuns

403: Token de API inválido ou usuário sem permissão.
NOTA: A geração de token só funciona para usuários com perfil ‘remote-login’.
404: Usuário não encontrado.
429: Muitas requisições. Tente novamente em instantes.
NOTA: O limite é de 100 requisições por minuto.

Fluxo

Gere o token conforme acima.
Redirecione o usuário para a URL retornada em login_url, podendo adicionar o parâmetro redirect para definir a página de destino após o login.

Exemplo de URL

https://sua_url_nevolus/custom-login?token=TOKEN_GERADO&redirect=https://seudominio.com/pagina-redirecionamento

O usuário será autenticado na Nevolus e redirecionado para a URL informada em redirect.
Se redirect não for informado, o usuário será direcionado para um página padrão de confirmação (OK).

Parâmetros

Parâmetro	Obrigatório	Descrição
token	Sim	Token de login gerado no passo anterior
redirect	Não	URL de destino após login (deve ser absoluta)

Endpoint

POST /wp-json/custom/v1/login-with-token

Headers obrigatórios

Header	Valor
Authorization	Bearer API_KEY
Content-Type	application/json
Accept	application/json

Body (JSON)

{
  "token": "TOKEN_GERADO"
}

Resposta de Sucesso (200)

{
  "cookies": [
    "w..._logged_in_...=...; path=/; HttpOnly; secure",
    "w..._sec_...=...; path=/w.-a...; HttpOnly; secure"
  ],
  "username": "NOME_DO_USUARIO"
}

cookies: Array com os cookies de sessão que devem ser enviados ao navegador do usuário via cabeçalho Set-Cookie.
username: Username autenticado.

Erros comuns

400: Token ausente.
403: Token inválido ou expirado.

Observações de Segurança

Sempre utilize HTTPS para todas as requisições.
O token de login é de uso único e expira em 5 minutos.
O endpoint requer autenticação via API Key no header Authorization.
O parâmetro redirect deve apontar para URLs confiáveis do próprio domínio.

Exemplo de Fluxo Completo

Login via Browser

POST /wp-json/custom/v1/generate-login-token com username.
Redirecione o usuário para a URL retornada em login_url, adicionando &redirect=URL_DE_DESTINO se desejar.

Login Transparente

POST /wp-json/custom/v1/generate-login-token com username.
POST /wp-json/custom/v1/login-with-token com o token retornado.
Injete os cookies retornados no navegador do usuário via cabeçalho Set-Cookie.

Exemplo de Requisição cURL

Gerar Token

curl -X POST "https://sua_url_nevolus/wp-json/custom/v1/generate-login-token" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"usuario"}'

Login Transparente

curl -X POST "https://sua_url_nevolus/wp-json/custom/v1/login-with-token" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_GERADO"}'

Exemplo de Injeção de Cookies com PHP e Python para Login Transparente (Backend)

O fluxo consiste em:

Gerar um token de login para o usuário.
Trocar o token por cookies de sessão usando o endpoint login-with-token.
Enviar (injetar) os cookies de sessão ao navegador do usuário via cabeçalho Set-Cookie, para que ele acesse os chatbots em modo autenticado.

PHP — Exemplo de Injeção de Cookies

<?php  
// 1. Gerar token de login  
$apiKey = 'SUA_API_KEY';
$username = 'usuario';

$ch = curl_init('https://sua_url_nevolus/wp-json/custom/v1/generate-login-token');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'username' => $username  
]));
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
$token = $data['login_token'];

// 2. Trocar token por cookies de sessão  
$ch = curl_init('https://sua_url_nevolus/wp-json/custom/v1/login-with-token');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'token' => $token  
]));
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
$cookies = $data['cookies'];

// 3. Injetar cookies no navegador do usuário  
foreach ($cookies as $cookieHeader) {
    header('Set-Cookie: ' . $cookieHeader, false);
}

// 4. Redirecionar usuário para a área logada (opcional)
header('Location: https://sua_url_nevolus/area-logada');
exit();
?>

Python (Flask) — Exemplo de Injeção de Cookies

from flask import Flask, redirect, make_response, request  
import requests

app = Flask(__name__)

API_KEY = 'SUA_API_KEY'
NEVOLUS_BASE_URL = 'https://sua_url_nevolus'

@app.route('/login_transparente')
def login_transparente():
    username = request.args.get('username')

    # 1. Gerar token de login  
    resp = requests.post(
        f'{NEVOLUS_BASE_URL}/wp-json/custom/v1/generate-login-token',
        headers={
            'Authorization': f'Bearer API_KEY',
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        },
        json={'username': username}
    )
    data = resp.json()
    token = data['login_token']

    # 2. Trocar token por cookies de sessão  
    resp2 = requests.post(
        f'{NEVOLUS_BASE_URL}/wp-json/custom/v1/login-with-token',
        headers={
            'Authorization': f'Bearer API_KEY',
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        },
        json={'token': token}
    )
    data2 = resp2.json()
    cookies = data2['cookies']

    # 3. Injetar cookies no navegador do usuário  
    response = make_response(redirect('https://sua_url_nevolus/area-logada'))
    for cookie_header in cookies:
        # Extraindo partes do cookie para setar manualmente  
        parts = cookie_header.split(';')
        key, value = parts[0].split('=', 1)
        options = {}
        for part in parts[1:]:
            if '=' in part:
                k, v = part.strip().split('=', 1)
                options[k.lower()] = v  
            else:
                options[part.strip().lower()] = True  
        response.set_cookie(key, value, path=options.get('path', '/'), httponly=options.get('httponly', False), secure=options.get('secure', False))
    return response

if __name__ == '__main__':
    app.run(debug=True)

Dica: Adapte a extração e definição de opções do cookie conforme necessário; frameworks como Flask ou Django possuem métodos próprios para set_cookie.

Observações Importantes

Sempre utilize HTTPS.
O login_token é de uso único e expira em 5 minutos.
Após injetar os cookies, redirecione o usuário para a página do chatbot ou para outra página conforme seu fluxo.

Endpoint

POST /wp-json/custom/v1/create-remote-user

Headers obrigatórios

Header	Valor
Authorization	Bearer API_KEY
Content-Type	application/json
Accept	application/json

Body (JSON)

{
  "username": "NOVO_USUARIO",
  "email": "email@dominio.com"
}

Resposta de Sucesso (200)

{
  "success": true,
  "username": "NOVO_USUARIO",
  "email": "email@dominio.com"
}

O usuário será criado com o papel remote-login.
Após a criação, o usuário poderá ser autenticado pelos fluxos de autenticação remota (via browser ou login transparente).

Erros comuns

400: Username ausente, muito longo ou email inválido.
409: Usuário ou email já cadastrado.
403: Token de API inválido.
429: Muitas requisições. Tente novamente em instantes.
Limite: 20 requisições por minuto.

Exemplo de requisição cURL

curl -X POST "https://sua_url_nevolus/wp-json/custom/v1/create-remote-user" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"novo_usuario","email":"novo@dominio.com"}'

Exemplo em PHP

<?php  
$apiKey = 'SUA_API_KEY';
$username = 'novo_usuario';
$email = 'novo@dominio.com';

$ch = curl_init('https://sua_url_nevolus/wp-json/custom/v1/create-remote-user');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'username' => $username,
    'email' => $email  
]));
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
if ($data['success']) {
    echo "Usuário criado: " . $data['username'];
} else {
    echo "Erro: " . $response;
}
?>

Exemplo em Python

import requests

API_KEY = 'SUA_API_KEY'
url = 'https://sua_url_nevolus/wp-json/custom/v1/create-remote-user'
payload = {
    "username": "novo_usuario",
    "email": "novo@dominio.com"
}
headers = {
    "Authorization": f"Bearer API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

Endpoint

POST /wp-json/custom/v1/delete-remote-user

Headers obrigatórios

Header	Valor
Authorization	Bearer API_KEY
Content-Type	application/json
Accept	application/json

Body (JSON)

{
  "username": "USUARIO_A_REMOVER"
}

Resposta de Sucesso (200)

{
  "success": true,
  "username": "USUARIO_A_REMOVER"
}

Apenas usuários com papel remote-login podem ser removidos por este endpoint.

Erros comuns

400: Username ausente ou muito longo.
404: Usuário não encontrado.
403: Usuário não possui o papel remote-login ou token de API inválido.
429: Muitas requisições. Tente novamente em instantes.
Limite: 20 requisições por minuto.

Exemplo de requisição cURL

curl -X POST "https://sua_url_nevolus/wp-json/custom/v1/delete-remote-user" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"usuario_a_remover"}'

Exemplo em PHP

<?php  
$apiKey = 'SUA_API_KEY';
$username = 'usuario_a_remover';

$ch = curl_init('https://sua_url_nevolus/wp-json/custom/v1/delete-remote-user');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'username' => $username  
]));
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
if ($data['success']) {
    echo "Usuário removido: " . $data['username'];
} else {
    echo "Erro: " . $response;
}
?>

Exemplo em Python

import requests

API_KEY = 'SUA_API_KEY'
url = 'https://sua_url_nevolus/wp-json/custom/v1/delete-remote-user'
payload = {
    "username": "usuario_a_remover"
}
headers = {
    "Authorization": f"Bearer API_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

Observações de Segurança

Apenas usuários com papel remote-login podem ser criados ou excluídos por estes endpoints.
Sempre utilize HTTPS para todas as requisições.
O endpoint requer autenticação via API Key no header Authorization.
Limite de 20 requisições por minuto por IP para criação e exclusão de usuários.

Em caso de dúvidas sobre integração, entre em contato consoco.

Nevolus IA – API de Autenticação Remota

Índice

Visão Geral

Observações de Segurança

Exemplo de Fluxo Completo

Exemplo de Requisição cURL

Exemplo de Injeção de Cookies com PHP e Python para Login Transparente (Backend)

PHP — Exemplo de Injeção de Cookies

Python (Flask) — Exemplo de Injeção de Cookies

Observações Importantes

Observações de Segurança

Categorias

Soluções

Empresa

Fale Conosco

Índice

Visão Geral

1. Gerar Token de Login

2. Login via Browser (Redirecionamento)

3. Login Transparente (Backend)

Observações de Segurança

Exemplo de Fluxo Completo

Exemplo de Requisição cURL

Exemplo de Injeção de Cookies com PHP e Python para Login Transparente (Backend)

PHP — Exemplo de Injeção de Cookies

Python (Flask) — Exemplo de Injeção de Cookies

Observações Importantes

4. Criar Usuário Remote-Login

5. Excluir Usuário Remote-Login

Observações de Segurança

Soluções

Empresa

Fale Conosco