Usuários & Autenticação

Os usuários staff são os recrutadores, gestores e administradores que operam o dia a dia do ATS. Cada usuário pertence a uma instância (ats) e pode ser vinculado a uma ou mais empresas com um papel (role), que define o que ele pode visualizar e gerenciar.

Esta página cobre o ciclo de vida completo do acesso: autenticação por e-mail e senha com token Bearer de 30 dias, consulta e edição do próprio perfil, troca de senha, logout e o gerenciamento de usuários da instância (restrito a owner/admin).

Headers obrigatórios

Todas as requisições devem incluir o header X-Ats-Id (UUID) com o identificador da instância ATS. Exceto o login, todos os endpoints exigem também Authorization: Bearer {token} de um usuário staff (guard atsUser).

Estrutura de Dados Principal

Um usuário staff contém as seguintes informações principais:

Campo	Tipo	Descrição
`firstName`	`String`	Nome do usuário (máx. 100 caracteres).
`lastName`	`String`	Sobrenome do usuário (máx. 100 caracteres).
`email`	`String`	E-mail de acesso (único por instância).
`jobTitle`	`String`	Cargo do usuário (opcional).
`avatarUrl`	`String`	URL do avatar (opcional).
`locale`	`String`	Idioma preferido do usuário (ex.: `pt-BR`).
`isActive`	`Boolean`	Indica se o usuário está ativo.
`lastLoginAt`	`Datetime`	Data/hora do último login.
`atsCompanyUsers`	`Array`	Vínculos do usuário com empresas da instância (com `role`).

Autenticação

Autentica um usuário staff com e-mail e senha, retornando um token Bearer válido por 30 dias. Este é o único endpoint público do grupo — não exige Authorization, apenas o X-Ats-Id da instância.

http

POST /v1/ats/user/users/login

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`email`	`string`	Sim	E-mail do usuário (deve existir na instância).
`password`	`string`	Sim	Senha do usuário.

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/users/login" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "johndoe@gmail.com",
    "password": "Password@123"
  }'

Respostas

200 OK

Retorna o token de acesso. Use o valor de token no header Authorization: Bearer {token} das demais requisições.

json

{
  "type": "bearer",
  "name": "6522b2f2-4101-4748-b7b1-f7716463e878",
  "token": "oat_Mw.Njh2OWRieE90NzF1NE1LaUhTUVFHSUJGNE02T3E3SFNiWUhESnNmeDM1MDAyNzQ2NzY",
  "abilities": [
    "*"
  ],
  "lastUsedAt": null,
  "expiresAt": "2026-10-10T03:04:39.783Z"
}

422 Unprocessable Entity

E-mail não encontrado na instância ou senha incorreta.

json

{
  "errors": [
    {
      "message": "Email/Senha inválida"
    }
  ]
}

Logout

Invalida o token Bearer usado na requisição. Após o logout, o token deixa de ser aceito imediatamente.

http

POST /v1/ats/user/users/logout

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/users/logout" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

Respostas

204 No Content

Token invalidado com sucesso.

Perfil do Usuário Autenticado

Endpoints para o usuário logado consultar e manter o próprio perfil.

Obter Perfil (Me)

Retorna os dados completos do usuário autenticado, incluindo os vínculos com empresas e seus papéis.

http

GET /v1/ats/user/users/me

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/users/me" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o perfil do usuário autenticado.

json

{
  "id": 1,
  "atsId": 1,
  "firstName": "Gerson",
  "lastName": "Tavares",
  "email": "gerson_tavares@live.com",
  "jobTitle": null,
  "avatarUrl": null,
  "locale": null,
  "isActive": true,
  "lastLoginAt": null,
  "createdAt": "2026-09-10T02:10:58.923+00:00",
  "updatedAt": "2026-09-10T02:10:58.923+00:00",
  "atsCompanyUsers": [
    {
      "id": 1,
      "atsCompanyId": 1,
      "role": "owner",
      "atsUserId": 1
    }
  ]
}

Atualizar Perfil (Me)

Atualiza os dados do próprio perfil. E-mail e senha não podem ser alterados por aqui — use o endpoint de troca de senha.

http

PUT /v1/ats/user/users/me

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`firstName`	`string`	Sim	Nome do usuário (máx. 100 caracteres).
`lastName`	`string`	Sim	Sobrenome do usuário (máx. 100 caracteres).
`jobTitle`	`string`	Não	Cargo (máx. 150 caracteres, pode ser nulo).
`avatarUrl`	`string`	Não	URL do avatar (máx. 250 caracteres, pode ser nulo).
`locale`	`string`	Não	Idioma preferido (máx. 10 caracteres, pode ser nulo).

Exemplo de Requisição

bash

curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/users/me" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe (updated)",
    "jobTitle": "Enginner Senior",
    "avatarUrl": null,
    "locale": "pt-BR"
  }'

Respostas

204 No Content

Perfil atualizado com sucesso.

422 Unprocessable Entity

Erro de validação nos campos enviados.

Trocar Senha

Altera a senha do usuário autenticado. A nova senha passa a valer no próximo login.

http

PATCH /v1/ats/user/users/change-password

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`password`	`string`	Sim	Nova senha (entre 8 e 32 caracteres).

Exemplo de Requisição

bash

curl -X PATCH "https://api.us.basis.tavares.in/v1/ats/user/users/change-password" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "Password@123"
  }'

Respostas

204 No Content

Senha alterada com sucesso.

422 Unprocessable Entity

Senha fora do intervalo de 8 a 32 caracteres.

Gerenciamento de Usuários

Endpoints de administração dos usuários staff da instância. A criação, atualização e remoção de usuários é restrita a usuários com papel owner ou admin (demais papéis recebem 403 FORBIDDEN).

Listar Usuários

Lista os usuários staff da instância, com paginação, busca e ordenação.

http

GET /v1/ats/user/users

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`page`	`number`	Não	O número da página (mínimo: 1).
`perPage`	`number`	Não	Itens por página (entre 1 e 100, padrão: 25).
`search`	`string`	Não	Busca por termo no nome ou e-mail (máx. 150 caracteres).
`orderBy`	`enum`	Não	Ordena por `id`, `firstName`, `email` ou `createdAt`.
`orderDirection`	`enum`	Não	Direção da ordenação: `asc` ou `desc`.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/users?page=1&perPage=25" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de usuários.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 1,
      "atsId": 1,
      "firstName": "Gerson",
      "lastName": "Tavares",
      "email": "gerson_tavares@live.com",
      "jobTitle": null,
      "avatarUrl": null,
      "locale": null,
      "isActive": true,
      "lastLoginAt": null,
      "createdAt": "2026-09-10T02:10:58.923+00:00",
      "updatedAt": "2026-09-10T02:10:58.923+00:00",
      "atsCompanyUsers": [
        {
          "id": 1,
          "atsCompanyId": 1,
          "role": "owner",
          "atsUserId": 1
        }
      ]
    }
  ]
}

Retorna os usuários em formato simplificado (label/value), ideal para selects e filtros no frontend.

http

GET /v1/ats/user/users/list

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/users/list" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um array com os usuários em formato label/value.

json

[
  {
    "label": "gerson_tavares@live.com",
    "value": 1
  },
  {
    "label": "johndoe@gmail.com",
    "value": 2
  }
]

Criar Usuário

Cria um novo usuário staff na instância. O e-mail deve ser único por instância. Apenas owner/admin.

http

POST /v1/ats/user/users

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`firstName`	`string`	Sim	Nome do usuário (máx. 100 caracteres).
`lastName`	`string`	Sim	Sobrenome do usuário (máx. 100 caracteres).
`email`	`string`	Sim	E-mail válido e único na instância (máx. 250 caracteres).
`password`	`string`	Sim	Senha inicial (entre 8 e 32 caracteres).
`jobTitle`	`string`	Não	Cargo (máx. 150 caracteres, pode ser nulo).
`avatarUrl`	`string`	Não	URL do avatar (máx. 250 caracteres, pode ser nulo).
`locale`	`string`	Não	Idioma preferido (máx. 10 caracteres, pode ser nulo).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/ats/user/users" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "johndoe@gmail.com",
    "password": "Password@123",
    "jobTitle": "Enginner Senior",
    "avatarUrl": null,
    "locale": "pt-BR"
  }'

Respostas

201 Created

Retorna o ID do usuário criado.

json

{
  "id": 2
}

422 Unprocessable Entity

Erro de validação nos campos enviados, incluindo e-mail já utilizado na instância.

json

{
  "errors": [
    {
      "message": "E-mail já está em uso",
      "rule": "database.unique",
      "field": "email"
    }
  ]
}

403 Forbidden

Ocorre quando o usuário autenticado não possui papel owner ou admin.

json

{
  "message": "Você não tem permissão para gerenciar este recurso",
  "code": "FORBIDDEN"
}

Obter Usuário por ID

Recupera os detalhes de um usuário staff, incluindo seus vínculos com empresas.

http

GET /v1/ats/user/users/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID do usuário.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/ats/user/users/2" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o usuário com seus vínculos em atsCompanyUsers.

json

{
  "id": 2,
  "atsId": 1,
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe@gmail.com",
  "jobTitle": "Enginner Senior",
  "avatarUrl": null,
  "locale": "pt-BR",
  "isActive": true,
  "lastLoginAt": null,
  "createdAt": "2026-09-10T03:10:15.103+00:00",
  "updatedAt": "2026-09-10T03:11:57.165+00:00",
  "atsCompanyUsers": []
}

404 Not Found

Ocorre quando o usuário não existe na instância.

Atualizar Usuário

Atualiza os dados de um usuário staff existente. Apenas owner/admin.

http

PUT /v1/ats/user/users/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID do usuário.

Payload (Body)

Aceita os mesmos campos da criação: firstName, lastName, email, password (opcional na atualização), jobTitle, avatarUrl e locale.

Exemplo de Requisição

bash

curl -X PUT "https://api.us.basis.tavares.in/v1/ats/user/users/2" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "johndoe@gmail.com",
    "password": "Password@123",
    "jobTitle": "Enginner Senior",
    "avatarUrl": null,
    "locale": "pt-BR"
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Erro de validação nos campos enviados, incluindo e-mail já utilizado por outro usuário da instância.

403 Forbidden

Ocorre quando o usuário autenticado não possui papel owner ou admin.

Remover Usuário

Remove um usuário staff da instância (soft delete — o registro deixa de aparecer em qualquer consulta). Apenas owner/admin.

http

DELETE /v1/ats/user/users/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID do usuário.

Exemplo de Requisição

bash

curl -X DELETE "https://api.us.basis.tavares.in/v1/ats/user/users/3" \
  -H "X-Ats-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}"

Respostas

204 No Content

Remoção concluída com sucesso.

403 Forbidden

Ocorre quando o usuário autenticado não possui papel owner ou admin.

Usuários & Autenticação ​

Estrutura de Dados Principal ​

Autenticação ​

Login ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Logout ​

Exemplo de Requisição ​

Respostas ​

Perfil do Usuário Autenticado ​

Obter Perfil (Me) ​

Exemplo de Requisição ​

Respostas ​

Atualizar Perfil (Me) ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Trocar Senha ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Gerenciamento de Usuários ​

Listar Usuários ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Listar Usuários (Dropdown) ​

Exemplo de Requisição ​

Respostas ​

Criar Usuário ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Usuário por ID ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Atualizar Usuário ​

Parâmetros de Rota ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Remover Usuário ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Usuários & Autenticação

Estrutura de Dados Principal

Autenticação

Login

Payload (Body)

Exemplo de Requisição

Respostas

Logout

Exemplo de Requisição

Respostas

Perfil do Usuário Autenticado

Obter Perfil (Me)

Exemplo de Requisição

Respostas

Atualizar Perfil (Me)

Payload (Body)

Exemplo de Requisição

Respostas

Trocar Senha

Payload (Body)

Exemplo de Requisição

Respostas

Gerenciamento de Usuários

Listar Usuários

Parâmetros de Query

Exemplo de Requisição

Respostas

Listar Usuários (Dropdown)

Exemplo de Requisição

Respostas

Criar Usuário

Payload (Body)

Exemplo de Requisição

Respostas

Obter Usuário por ID

Parâmetros de Rota

Exemplo de Requisição

Respostas

Atualizar Usuário

Parâmetros de Rota

Payload (Body)

Exemplo de Requisição

Respostas

Remover Usuário

Parâmetros de Rota

Exemplo de Requisição

Respostas