Início de sessão e sessões

Métodos, campos dos pedidos e respostas.

Guia completo

Esta secção contém 14 métodos. Abra o método para consultar as condições de acesso, os campos do pedido e a resposta.

Método e caminho	Descrição	Acesso
`POST /api/v1/auth/forgot-password`	Pedido de reposição da palavra-passe	Sem iniciar sessão; as condições adicionais estão indicadas no método
`POST /api/v1/auth/login`	Início de sessão com e-mail e palavra-passe	Sem iniciar sessão; as condições adicionais estão indicadas no método
`POST /api/v1/auth/login/2fa`	Conclusão do início de sessão com TOTP	Sem iniciar sessão; as condições adicionais estão indicadas no método
`POST /api/v1/auth/logout`	Terminar sessão e revogar o refresh token	Sem iniciar sessão; as condições adicionais estão indicadas no método
`GET /api/v1/auth/me`	Utilizador atual, saldo e limites	Token da área pessoal
`POST /api/v1/auth/passkey/login/begin`	Início da autenticação com passkey	Sem iniciar sessão; as condições adicionais estão indicadas no método
`POST /api/v1/auth/passkey/login/finish`	Conclusão da autenticação com passkey	Sem iniciar sessão; as condições adicionais estão indicadas no método
`POST /api/v1/auth/refresh`	Atualização de tokens	Sem iniciar sessão; as condições adicionais estão indicadas no método
`POST /api/v1/auth/register`	Registar-se	Sem iniciar sessão; as condições adicionais estão indicadas no método
`POST /api/v1/auth/reset-password`	Reposição da palavra-passe	Sem iniciar sessão; as condições adicionais estão indicadas no método
`POST /api/v1/auth/revoke-all-sessions`	Revogação de todas as sessões	Token da área pessoal
`POST /api/v1/auth/send-verify-code`	Envio do código de confirmação	Sem iniciar sessão; as condições adicionais estão indicadas no método
`POST /api/v1/auth/validate-invitation-code`	Validação do convite	Sem iniciar sessão; as condições adicionais estão indicadas no método
`POST /api/v1/auth/validate-promo-code`	Validação do código promocional	Sem iniciar sessão; as condições adicionais estão indicadas no método

POST /api/v1/auth/forgot-password — Pedido de reposição da palavra-passe

Acesso: sem iniciar sessão; as condições adicionais estão indicadas no método

Limite de frequência: 5 pedidos em 60 segundos a partir de um único endereço.

POST/api/v1/auth/forgot-password

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`email`	`string`	sim	required,email
`turnstile_token`	`string`	não

Modelo do corpo do pedido

{
  "email": "PLACEHOLDER_EMAIL (string)",
  "turnstile_token": "PLACEHOLDER_TURNSTILE_TOKEN (string)"
}

PLACEHOLDER representa os seus dados de entrada e o respetivo tipo. Substitua os valores e mantenha apenas os campos opcionais necessários; não envie marcadores de texto no lugar de números, booleanos, objetos ou arrays.

Esquema do pedido: ForgotPasswordRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: ForgotPasswordResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "PLACEHOLDER_MESSAGE (string)"
  }
}

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

POST /api/v1/auth/login — Início de sessão com e-mail e palavra-passe

Acesso: sem iniciar sessão; as condições adicionais estão indicadas no método

A disponibilidade da funcionalidade e as condições adicionais de acesso são verificadas ao executar o pedido.

Limite de frequência: 20 pedidos em 60 segundos a partir de um único endereço.

POST/api/v1/auth/login

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`email`	`string`	sim	required,email
`password`	`string`	sim	required
`turnstile_token`	`string`	não

Modelo do corpo do pedido

{
  "email": "PLACEHOLDER_EMAIL (string)",
  "password": "PLACEHOLDER_PASSWORD (string)",
  "turnstile_token": "PLACEHOLDER_TURNSTILE_TOKEN (string)"
}

Esquema do pedido: LoginRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: TotpLoginResponse, User, AuthResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Se forem possíveis várias variantes de resposta, os respetivos campos são apresentados em esquemas separados; não devem ser combinados num único objeto.

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

POST /api/v1/auth/login/2fa — Conclusão do início de sessão com TOTP

Acesso: sem iniciar sessão; as condições adicionais estão indicadas no método

A disponibilidade da funcionalidade e as condições adicionais de acesso são verificadas ao executar o pedido.

Limite de frequência: 20 pedidos em 60 segundos a partir de um único endereço.

POST/api/v1/auth/login/2fa

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`temp_token`	`string`	sim	required
`totp_code`	`string`	sim	required,len=6

Modelo do corpo do pedido

{
  "temp_token": "PLACEHOLDER_TEMP_TOKEN (string)",
  "totp_code": "PLACEHOLDER_TOTP_CODE (string)"
}

Esquema do pedido: Login2FARequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: User, AuthResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Se forem possíveis várias variantes de resposta, os respetivos campos são apresentados em esquemas separados; não devem ser combinados num único objeto.

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

POST /api/v1/auth/logout — Terminar sessão e revogar o refresh token

Acesso: sem iniciar sessão; as condições adicionais estão indicadas no método

POST/api/v1/auth/logout

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`refresh_token`	`string`	não	; Opcional: revogar o token de atualização indicado

Modelo do corpo do pedido

{
  "refresh_token": "PLACEHOLDER_REFRESH_TOKEN (string)"
}

Esquema do pedido: LogoutRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: LogoutResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "PLACEHOLDER_MESSAGE (string)"
  }
}

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

GET /api/v1/auth/me — Utilizador atual, saldo e limites

Acesso: token da área pessoal

GET/api/v1/auth/me

Leitura; o ID é obtido da sua resposta anterior

curl --fail-with-body "https://ailoot.ai/api/v1/auth/me" \
  -H "Authorization: Bearer $TOKEN"

Não é necessário corpo do pedido. Transmita os parâmetros indicados acima no URL.

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: User, UserProfileResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "email": "PLACEHOLDER_EMAIL (string)",
    "username": "PLACEHOLDER_USERNAME (string)",
    "role": "PLACEHOLDER_ROLE (string)",
    "balance": "PLACEHOLDER_BALANCE (number)",
    "frozen_balance": "PLACEHOLDER_FROZEN_BALANCE (number)",
    "concurrency": "PLACEHOLDER_CONCURRENCY (integer)",
    "status": "PLACEHOLDER_STATUS (string)",
    "last_active_at": "PLACEHOLDER_LAST_ACTIVE_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "deleted_at": "PLACEHOLDER_DELETED_AT (string)",
    "balance_notify_enabled": "PLACEHOLDER_BALANCE_NOTIFY_ENABLED (boolean)",
    "balance_notify_threshold_type": "PLACEHOLDER_BALANCE_NOTIFY_THRESHOLD_TYPE (string)",
    "balance_notify_threshold": "PLACEHOLDER_BALANCE_NOTIFY_THRESHOLD (number)",
    "balance_notify_extra_emails": "PLACEHOLDER_BALANCE_NOTIFY_EXTRA_EMAILS (array)",
    "total_recharged": "PLACEHOLDER_TOTAL_RECHARGED (number)",
    "rpm_limit": "PLACEHOLDER_RPM_LIMIT (integer)",
    "api_keys": "PLACEHOLDER_API_KEYS (array)",
    "avatar_url": "PLACEHOLDER_AVATAR_URL (string)",
    "email_bound": "PLACEHOLDER_EMAIL_BOUND (boolean)"
  }
}

Particularidades: todos os dados pessoais e objetos estão limitados ao sujeito do JWT.

Particularidades: os limites de despesas das chaves (quota, quota_used) são apresentados na resposta das chaves, e não no perfil. frozen_balance é o valor reservado e não pode ser considerado saldo disponível.

POST /api/v1/auth/passkey/login/begin — Início da autenticação com passkey

Acesso: sem iniciar sessão; as condições adicionais estão indicadas no método

A disponibilidade da funcionalidade e as condições adicionais de acesso são verificadas ao executar o pedido.

Limite de frequência: 20 pedidos em 60 segundos a partir de um único endereço.

POST/api/v1/auth/passkey/login/begin

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`turnstile_token`	`string`	não

Modelo do corpo do pedido

{
  "turnstile_token": "PLACEHOLDER_TURNSTILE_TOKEN (string)"
}

Esquema do pedido: PasskeyBeginLoginRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: PasskeyOptionsResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "session_token": "PLACEHOLDER_SESSION_TOKEN (string)",
    "options": "PLACEHOLDER_OPTIONS (any)"
  }
}

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

Particularidades: credential é obtido de navigator.credentials; session_token vem de begin. Corpo de finish <=65536 bytes; o registo e a eliminação exigem palavra-passe.

POST /api/v1/auth/passkey/login/finish — Conclusão da autenticação com passkey

Acesso: sem iniciar sessão; as condições adicionais estão indicadas no método

A disponibilidade da funcionalidade e as condições adicionais de acesso são verificadas ao executar o pedido.

Limite de frequência: 20 pedidos em 60 segundos a partir de um único endereço.

POST/api/v1/auth/passkey/login/finish

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`session_token`	`string`	sim	required
`name`	`string`	não
`credential`	`object`	sim	required

Modelo do corpo do pedido

{
  "session_token": "PLACEHOLDER_SESSION_TOKEN (string)",
  "name": "PLACEHOLDER_NAME (string)",
  "credential": "PLACEHOLDER_CREDENTIAL (object)"
}

Esquema do pedido: PasskeyFinishRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: User, AuthResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Se forem possíveis várias variantes de resposta, os respetivos campos são apresentados em esquemas separados; não devem ser combinados num único objeto.

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

Particularidades: credential é obtido de navigator.credentials; session_token vem de begin. Corpo de finish <=65536 bytes; o registo e a eliminação exigem palavra-passe.

POST /api/v1/auth/refresh — Atualização de tokens

Acesso: sem iniciar sessão; as condições adicionais estão indicadas no método

A disponibilidade da funcionalidade e as condições adicionais de acesso são verificadas ao executar o pedido.

Limite de frequência: 30 pedidos em 60 segundos a partir de um único endereço.

POST/api/v1/auth/refresh

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`refresh_token`	`string`	sim	required

Modelo do corpo do pedido

{
  "refresh_token": "PLACEHOLDER_REFRESH_TOKEN (string)"
}

Esquema do pedido: RefreshTokenRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: RefreshTokenResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "PLACEHOLDER_ACCESS_TOKEN (string)",
    "refresh_token": "PLACEHOLDER_REFRESH_TOKEN (string)",
    "expires_in": "PLACEHOLDER_EXPIRES_IN (integer)",
    "token_type": "PLACEHOLDER_TOKEN_TYPE (string)"
  }
}

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

POST /api/v1/auth/register — Registo

Acesso: sem iniciar sessão; as condições adicionais estão indicadas no método

Limite de frequência: 5 pedidos em 60 segundos a partir de um único endereço.

POST/api/v1/auth/register

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`email`	`string`	sim	required,email
`password`	`string`	sim	required,min=6
`verify_code`	`string`	não
`turnstile_token`	`string`	não
`promo_code`	`string`	não	; Código promocional de registo
`invitation_code`	`string`	não	; Código de convite

Modelo do corpo do pedido

{
  "email": "PLACEHOLDER_EMAIL (string)",
  "password": "PLACEHOLDER_PASSWORD (string)",
  "verify_code": "PLACEHOLDER_VERIFY_CODE (string)",
  "turnstile_token": "PLACEHOLDER_TURNSTILE_TOKEN (string)",
  "promo_code": "PLACEHOLDER_PROMO_CODE (string)",
  "invitation_code": "PLACEHOLDER_INVITATION_CODE (string)"
}

Esquema do pedido: RegisterRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: User, AuthResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Se forem possíveis várias variantes de resposta, os respetivos campos são apresentados em esquemas separados; não devem ser combinados num único objeto.

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

POST /api/v1/auth/reset-password — Reposição da palavra-passe

Acesso: sem iniciar sessão; as condições adicionais estão indicadas no método

Limite de frequência: 10 pedidos em 60 segundos a partir de um único endereço.

POST/api/v1/auth/reset-password

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`email`	`string`	sim	required,email
`token`	`string`	sim	required
`new_password`	`string`	sim	required,min=6

Modelo do corpo do pedido

{
  "email": "PLACEHOLDER_EMAIL (string)",
  "token": "PLACEHOLDER_TOKEN (string)",
  "new_password": "PLACEHOLDER_NEW_PASSWORD (string)"
}

Esquema do pedido: ResetPasswordRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: ResetPasswordResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "PLACEHOLDER_MESSAGE (string)"
  }
}

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

POST /api/v1/auth/revoke-all-sessions — Revogação de todas as sessões

Acesso: token da área pessoal

POST/api/v1/auth/revoke-all-sessions

Não é necessário corpo do pedido.

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: RevokeAllSessionsResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "PLACEHOLDER_MESSAGE (string)"
  }
}

Particularidades: todos os dados pessoais e objetos estão limitados ao sujeito do JWT.

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

POST /api/v1/auth/send-verify-code — Envio do código de confirmação

Acesso: sem iniciar sessão; as condições adicionais estão indicadas no método

Limite de frequência: 5 pedidos em 60 segundos a partir de um único endereço.

POST/api/v1/auth/send-verify-code

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`email`	`string`	sim	required,email
`turnstile_token`	`string`	não

Modelo do corpo do pedido

{
  "email": "PLACEHOLDER_EMAIL (string)",
  "turnstile_token": "PLACEHOLDER_TURNSTILE_TOKEN (string)"
}

Esquema do pedido: SendVerifyCodeRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: SendVerifyCodeResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "PLACEHOLDER_MESSAGE (string)",
    "countdown": "PLACEHOLDER_COUNTDOWN (integer)"
  }
}

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

POST /api/v1/auth/validate-invitation-code — Validação do convite

Acesso: sem iniciar sessão; as condições adicionais estão indicadas no método

A disponibilidade da funcionalidade e as condições adicionais de acesso são verificadas ao executar o pedido.

Limite de frequência: 10 pedidos em 60 segundos a partir de um único endereço.

POST/api/v1/auth/validate-invitation-code

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`code`	`string`	sim	required

Modelo do corpo do pedido

{
  "code": "PLACEHOLDER_CODE (string)"
}

Esquema do pedido: ValidateInvitationCodeRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: ValidateInvitationCodeResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "valid": "PLACEHOLDER_VALID (boolean)",
    "error_code": "PLACEHOLDER_ERROR_CODE (string)"
  }
}

Particularidades: o método verifica o convite e não consome o código; o exemplo descreve o contrato e não é executado.

POST /api/v1/auth/validate-promo-code — Validação do código promocional

Acesso: sem iniciar sessão; as condições adicionais estão indicadas no método

A disponibilidade da funcionalidade e as condições adicionais de acesso são verificadas ao executar o pedido.

Limite de frequência: 10 pedidos em 60 segundos a partir de um único endereço.

POST/api/v1/auth/validate-promo-code

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`code`	`string`	sim	required

Modelo do corpo do pedido

{
  "code": "PLACEHOLDER_CODE (string)"
}

Esquema do pedido: ValidatePromoCodeRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: ValidatePromoCodeResponse. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "valid": "PLACEHOLDER_VALID (boolean)",
    "bonus_amount": "PLACEHOLDER_BONUS_AMOUNT (number)",
    "error_code": "PLACEHOLDER_ERROR_CODE (string)",
    "message": "PLACEHOLDER_MESSAGE (string)"
  }
}

Particularidades: o método verifica o código promocional e não credita o bónus; o exemplo descreve o contrato e não é executado.

Início de sessão e sessões · 2FA

POST /api/v1/auth/login → data

data.requires_2fa === true → TotpLoginResponse → data.temp_token → POST /api/v1/auth/login/2fa · {"temp_token": "…", "totp_code": "…"} → data.access_token
data.access_token → AuthResponse → Authorization: Bearer $TOKEN

totp_code: string, len = 6. temp_token ≠ access_token. User

Ainda tem dúvidas? Envie o Request ID e uma descrição — ajudamos a esclarecer.Contactar o suporte