User Accounts API – Registration & Auth | GOAT Portfolio

Overview

The Users API handles the full account lifecycle: creating a new account, verifying the registered email address, authenticating to receive a JWT, and recovering or resetting a forgotten password. All request and response bodies use JSON unless otherwise noted.

POST /api/usuario/pre-registro

Register a new user account. On success the server dispatches a verification email to the provided address; the account cannot log in until that link is clicked.

Request Body

nombre

string

required

First name of the user. Must contain letters only (no digits). Accepts Spanish-language accented characters and spaces.

apellido_paterno

string

required

Paternal (first) surname. Letters only — the same character restrictions as nombre apply.

apellido_materno

string

required

Maternal (second) surname. Letters only.

string

required

A valid, unique email address. This is used for verification and login.

contrasena

string

required

Account password. Minimum 6 characters.

contrasena_confirmation

string

required

Password confirmation field. Must be identical to contrasena.

Responses

message

string

Human-readable confirmation that a verification email has been dispatched.

Status	Meaning
`200`	Registration accepted — verification email sent.
`422`	Validation failed. The `errors` object maps field names to error messages.

422 error shape

{
  "errors": {
    "email": "The email has already been taken.",
    "contrasena": "The contrasena must be at least 6 characters."
  }
}

Example Request

curl -X POST https://api.goatportfolio.com/api/usuario/pre-registro \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "nombre": "María",
    "apellido_paterno": "González",
    "apellido_materno": "López",
    "email": "maria@example.com",
    "contrasena": "s3cur3pass",
    "contrasena_confirmation": "s3cur3pass"
  }'

Example Response

{
  "message": "We have sent a verification link to your email address. Please check your inbox."
}

GET /api/usuario/verificar-email/:token

Verify the user’s email address using the token embedded in the registration confirmation email. This endpoint is typically accessed by clicking the link in the email client rather than called directly from application code.

Path Parameters

token

string

required

The unique verification token sent to the user’s email address upon registration.

Responses

Status	Meaning
`200`	Email verified successfully. The response either redirects the browser to the login page or returns a success message body.
`400` / `422`	The token is invalid, expired, or has already been used.

Authenticate with email and password. Returns a signed JWT and the user’s profile data on success.

Request Body

string

required

The email address registered to the account.

contrasena

string

required

The account password.

Responses

token

string

Signed JWT to be sent as Authorization: Bearer <token> in subsequent authenticated requests.

usuario

object

Core user profile object.

Show usuario fields

id_usuario

string

Unique identifier for the user.

nombre

string

User’s first name.

string

User’s email address.

id_portafolio

string

Portfolio ID nested on the user object. May be present here as a fallback if the top-level id_portafolio field is absent.

tipo_usuario

string

Account role — either 'admin' or a standard user role. May also be returned at the top level (see tipo_usuario below).

id_portafolio

string

The ID of the user’s portfolio at the top level. If absent, fall back to usuario.id_portafolio. Store this value in your client to use with portfolio and project endpoints.

tipo_usuario

string

Account role returned at the top level — either 'admin' or a standard user role. If absent, fall back to usuario.tipo_usuario. Use this to redirect admin users to the admin dashboard after login.

Status	Meaning
`200`	Login successful — token and profile returned.
`401`	Invalid email or password.
`403`	Account has been suspended. The `message` field contains details.
`422`	Validation errors on the request fields.

Example Request

curl -X POST https://api.goatportfolio.com/api/usuario/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "maria@example.com",
    "contrasena": "s3cur3pass"
  }'

Example Response

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "usuario": {
    "id_usuario": "01HXYZ123456789",
    "nombre": "María",
    "email": "maria@example.com",
    "id_portafolio": "01HXYZ987654321",
    "tipo_usuario": "usuario"
  },
  "id_portafolio": "01HXYZ987654321",
  "tipo_usuario": "usuario"
}

After a successful login, persist the token and id_portafolio values on the client (e.g. localStorage). They are required by all authenticated endpoints. The client reads id_portafolio as data.id_portafolio ?? data.usuario?.id_portafolio. Similarly, tipo_usuario is read as data.tipo_usuario ?? data.usuario?.tipo_usuario. If the resolved tipo_usuario is 'admin', redirect the user to the admin dashboard.

POST /api/usuario/contrasena/olvido

Request a password reset email. If the email address is associated with an active account, the server sends a time-limited reset link.

Request Body

string

required

The email address registered to the account that needs a password reset.

Responses

message

string

Confirmation that the reset email has been dispatched (or a generic message when the address is not found, to prevent account enumeration).

Status	Meaning
`200`	Request processed — reset email sent if the address exists.
`422`	Invalid or missing email field.

Example Request

curl -X POST https://api.goatportfolio.com/api/usuario/contrasena/olvido \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "email": "maria@example.com" }'

Example Response

{
  "message": "If an account exists for that email, a password reset link has been sent."
}

POST /api/usuario/contrasena/restablecer

Reset the account password using the token received by email from the forgot-password flow. The reset link in the recovery email directs users to the /reset-password client-side route, which calls this server endpoint.

Verify the exact endpoint path against your backend configuration. The forgot-password flow dispatches the reset link; the path below reflects the expected server route.

Request Body

token

string

required

The password reset token extracted from the link in the recovery email.

contrasena

string

required

The new password. Must be at least 6 characters.

contrasena_confirmation

string

required

Must match contrasena exactly.

Responses

message

string

Confirmation that the password has been updated successfully.

Status	Meaning
`200`	Password reset successfully.
`400` / `422`	Token is invalid or expired, or the passwords do not match.

Example Request

curl -X POST https://api.goatportfolio.com/api/usuario/contrasena/restablecer \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "token": "abc123resettoken",
    "contrasena": "newS3curePass",
    "contrasena_confirmation": "newS3curePass"
  }'

Example Response

{
  "message": "Your password has been reset successfully. You can now log in."
}

Overview

Endpoints

User Accounts API – Registration & Auth | GOAT Portfolio

Overview

POST /api/usuario/pre-registro

Request Body

Responses

Example Request

Example Response

GET /api/usuario/verificar-email/:token

Path Parameters

Responses

Request Body

Responses

Example Request

Example Response

POST /api/usuario/contrasena/olvido

Request Body

Responses

Example Request

Example Response

POST /api/usuario/contrasena/restablecer

Request Body

Responses

Example Request

Example Response

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Overview

​POST /api/usuario/pre-registro

​Request Body

​Responses

​Example Request

​Example Response

​GET /api/usuario/verificar-email/:token

​Path Parameters

​Responses

​POST /api/usuario/login

​Request Body

​Responses

​Example Request

​Example Response

​POST /api/usuario/contrasena/olvido

​Request Body

​Responses

​Example Request

​Example Response

​POST /api/usuario/contrasena/restablecer

​Request Body

​Responses

​Example Request

​Example Response

Build docs developers (and LLMs) love

Overview

POST /api/usuario/pre-registro

Request Body

Responses

Example Request

Example Response

GET /api/usuario/verificar-email/:token

Path Parameters

Responses

POST /api/usuario/login

Request Body

Responses

Example Request

Example Response

POST /api/usuario/contrasena/olvido

Request Body

Responses

Example Request

Example Response

POST /api/usuario/contrasena/restablecer

Request Body

Responses

Example Request

Example Response