Documentação

AuthServer — Sistema centralizado de autenticação multi-tenant.

Introdução

O AuthServer é um sistema de autenticação centralizado que permite gerir utilizadores, tenants (organizações), aplicações e permissões num único local.

Cada utilizador pode pertencer a múltiplos tenants. Cada tenant pode ter múltiplas aplicações. Cada aplicação tem as suas próprias permissões/rules.

Base URL: https://auth.wiot.network

Formato: JSON — todas as respostas seguem o formato { success, message, data, timestamp }

API

Todas as rotas API estão sob /api/v1/. As rotas protegidas exigem Authorization: Bearer <token>.

Autenticação

POST /api/v1/auth/login

Login com email/username + password.

curl -X POST https://auth.wiot.network/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"identifier":"admin@exemplo.com","password":"123456"}'
POST /api/v1/auth/magic-link

Solicita um link mágico para o email do utilizador.

curl -X POST https://auth.wiot.network/api/v1/auth/magic-link \
  -H "Content-Type: application/json" \
  -d '{"identifier":"admin@exemplo.com"}'
POST /api/v1/auth/magic-link/verify

Verifica o token do link mágico e retorna os tokens de acesso.

curl -X POST https://auth.wiot.network/api/v1/auth/magic-link/verify \
  -H "Content-Type: application/json" \
  -d '{"token":"...","email":"admin@exemplo.com"}'
POST /api/v1/auth/pin

Solicita um PIN de 6 dígitos para o email.

curl -X POST https://auth.wiot.network/api/v1/auth/pin \
  -H "Content-Type: application/json" \
  -d '{"identifier":"admin@exemplo.com"}'
POST /api/v1/auth/pin/verify

Verifica o PIN e retorna os tokens de acesso.

curl -X POST https://auth.wiot.network/api/v1/auth/pin/verify \
  -H "Content-Type: application/json" \
  -d '{"pin":"123456","email":"admin@exemplo.com"}'
POST /api/v1/auth/refresh

Renova o access token usando um refresh token.

curl -X POST https://auth.wiot.network/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"..."}'
GET /api/v1/auth/me Auth required

Retorna os dados do utilizador autenticado, tenants e permissões.

curl https://auth.wiot.network/api/v1/auth/me \
  -H "Authorization: Bearer <token>"
POST /api/v1/auth/logout Auth required

Revoga todos os tokens do utilizador.

curl -X POST https://auth.wiot.network/api/v1/auth/logout \
  -H "Authorization: Bearer <token>"

Utilizadores

GET /api/v1/users

Lista utilizadores (paginado).

Parâmetros: page, perPage, search, tenantId

POST /api/v1/users

Cria um novo utilizador.

curl -X POST https://auth.wiot.network/api/v1/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "joao",
    "email": "joao@exemplo.com",
    "password": "Secure123!",
    "displayName": "João Silva",
    "tenantId": 1
  }'

Tenants

Um tenant representa uma organização ou projeto. Cada tenant pode ter várias aplicações.

GET /api/v1/tenants

Lista todos os tenants.

POST /api/v1/tenants 
curl -X POST https://auth.wiot.network/api/v1/tenants \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Empresa XYZ","slug":"empresa-xyz"}'

Permissões / Rules

As permissões são definidas por aplicação. Cada permissão tem um slug único (ex: verCidades) e um tipo (boolean, string, array, number).

POST /api/v1/permissions 
curl -X POST https://auth.wiot.network/api/v1/permissions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": 1,
    "name": "Ver Cidades",
    "slug": "verCidades",
    "type": "array"
  }'
POST /api/v1/permissions/assign

Atribui uma permissão a um utilizador.

curl -X POST https://auth.wiot.network/api/v1/permissions/assign \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "permissionId": 1,
    "appId": 1,
    "value": ["Lisboa", "Porto"]
  }'

SDKs

PHP

O SDK PHP gere automaticamente a sessão, refresh de tokens, e tratamento de erros.

<?php
require_once 'sdk/php/AuthClient.php';

$auth = new AuthClient('https://auth.wiot.network');

// Login com password
$auth->login('email@exemplo.com', 'password', $tenantId);

// Ou com magic link
$auth->loginWithMagicLink('token', 'email@exemplo.com');

// Ou com PIN
$auth->loginWithPin('123456', 'email@exemplo.com');

// Dados do utilizador
$user = $auth->me();
$tenants = $user['data']['tenants'];

// Mudar de tenant
$auth->switchTenant(2);

Python

from sdk.py.auth_client import AuthClient

auth = AuthClient('https://auth.wiot.network')
auth.login('email@exemplo.com', 'password')

# Ver perfil
profile = auth.me()
print(profile['data']['user'])

# Logout
auth.logout()

JavaScript

import { AuthClient } from './sdk/js/auth-client.js';

const auth = new AuthClient('https://auth.wiot.network');

await auth.login('email@exemplo.com', 'password');
const profile = await auth.me();
console.log(profile.data.user);

Exemplo de Fluxo

Fluxo típico de autenticação para uma aplicação de eletricidade:

  1. O técnico abre a app mobile e faz login via API
  2. O AuthServer valida as credenciais e retorna JWT + refresh token
  3. A app guarda o token e faz pedidos à API de backend com Authorization: Bearer
  4. O backend verifica as permissões do técnico (ex: verCidades, limiteTecnicos)
  5. Quando o token expira, o SDK faz refresh automático