Contas e usuários
Esta página lista os endpoints HTTP para gerenciar contas e seus usuários. O modelo de token e os escopos de acesso estão em Autenticação; o envelope Ok/Err, os códigos de status e a escrita condicional (ETag/If-Match) estão em Convenções e erros. A coluna Acesso indica o privilégio mínimo.
Contas
| Método | Caminho | Acesso | Corpo | Descrição |
|---|---|---|---|---|
POST | /accounts | Publico | account_name, user_email, user_name, user_phone (opcional), password | Cadastro: cria uma conta e seu primeiro usuário dono. Dispara e-mail de verificação ao novo usuário. Recusa se já existir usuário com aquele e-mail. |
POST | /accounts/new | Token de usuario | account_name | Cria uma conta adicional para o usuário autenticado (não cria usuário novo). |
GET | /accounts | Token de usuario | sem corpo | Lista as contas que o usuário autenticado acessa. Retorna uma lista de contas, sem ETag por item. |
GET | /accounts/this | ReadOnly | sem corpo | Detalhes da conta atual. |
PUT | /accounts | Token de usuario | account_name | Com If-Match, renomeia a conta; o chamador precisa ser membro Owner ou Admin dela. Sem If-Match, cria uma conta. Retorna o novo ETag no cabeçalho. |
DELETE | /accounts/this | Admin | sem corpo | Exclui a conta atual. Retorna { "deleted": <bool> }. |
POST | /accounts/this/owner | Owner | user_email | Transfere a posse da conta, pelo e-mail, a um membro desta conta com e-mail verificado (senão 400). O dono atual passa a Standard e o alvo vira Owner. É o único endpoint desta página que um Admin não chama. |
GET | /accounts/this/blocked/stats | ReadOnly | since (query, opcional), until (query, opcional), step (query, opcional) | Estatísticas de tráfego bloqueado da conta atual. Retorna data: uma lista de { epoch, count }, com até 1000 pontos. |
Nota
GET /accounts/this retorna account_name, plan_name (opcional), account_status, account_status_since, access_type (opcional), features (lista) e etag; o mesmo ETag vem no cabeçalho ETag e serve para a escrita condicional de PUT /accounts. GET /accounts não traz ETag por item.
Em GET /accounts/this/blocked/stats, since e until são timestamps e a janela padrão é os últimos 7 dias. step é o intervalo de agregação: minute, hour, day (padrão), week, year ou all (agrega tudo num único ponto), e a grafia antiga com inicial maiúscula ainda é aceita; não existe granularidade month.
Usuários
| Método | Caminho | Acesso | Corpo | Descrição |
|---|---|---|---|---|
GET | /users | ReadOnly | sem corpo | Lista os usuários da conta. Retorna um objeto com a chave users (não um array no topo, ao contrário de GET /accounts). Cada item traz user_email, user_name, is_email_verified, access_type e etag. |
POST | /users | Admin | user_name, user_email, access_type (Admin, Standard ou ReadOnly) | Convida/cria um usuário na conta. Dispara e-mail de convite/verificação. |
PUT | /users | Admin (opcional) | user_email, user_name, user_phone (opcional), password (opcional), access_type (opcional; Admin, Standard ou ReadOnly) | Com If-Match, atualiza o usuário existente: user_name, user_phone, password se enviada e o access_type do usuário nesta conta. Trocar access_type exige token de conta Admin ou Owner (senão 401). Sem If-Match, cria um usuário dono (cadastro self-service, exige password). Retorna o novo ETag no cabeçalho. |
DELETE | /users/{user_email} | Admin | sem corpo | Remove o usuário pelo e-mail. Não remove o dono (400). Expira imediatamente todos os tokens ativos daquele usuário na conta, revogando o acesso na hora. Retorna <bool> (se removeu). |
POST | /users/{user_email}/resend-verification-email | Standard | user_email | Reenvia o e-mail de verificação a um usuário da conta que ainda não verificou o endereço. |
GET | /users/verify-email | Publico | email_verification_token (query) | Confirma o e-mail a partir do token recebido por e-mail. Retorna <bool>. |
POST | /users/access-account | Publico | email_verification_token, password | Ativa o acesso de um usuário convidado: define a senha a partir do token de verificação. Retorna <bool>. |
PUT | /users/password | Token de usuario | password | Troca a senha do próprio usuário autenticado. Mesma operação de PUT /auth-methods/password; métodos de login em Autenticação. |
Nota
Uma conta tem quatro níveis: Owner, Admin, Standard e ReadOnly. Owner é único; Admin não (uma conta pode ter vários). Na criação e na edição de usuário, access_type aceita Admin, Standard e ReadOnly; Owner é recusado com 400. A posse muda apenas por POST /accounts/this/owner, o único endpoint que um Admin não chama. GET /users retorna um etag por usuário para escrita condicional.
A senha precisa ter no mínimo 8 caracteres e não pode conter o caractere :; violação retorna 400. A regra vale em todo endpoint que aceita password: POST /accounts, PUT /users (sempre que password vier, na criação e na atualização com If-Match), POST /users/access-account e PUT /users/password (e PUT /auth-methods/password, em Autenticação).
Veja também
- Início rápido: tutorial que usa estes endpoints.
- Autenticação: modelo de token e escopos de acesso.
- Convenções e erros: envelope, status e escrita condicional.