Authentication API: register, login, and session management

Krafta handles identity with a custom HMAC-SHA256 JWT implementation that runs entirely in Next.js Route Handlers — no third-party auth library is required. Every successful authentication call sets a krafta-token HttpOnly cookie that the browser sends automatically on subsequent requests. Passwords are hashed with PBKDF2-SHA512 before storage.

POST /api/auth/register

Creates a new user account with the default CLIENTE role, signs a JWT, and sets the session cookies immediately so the user is logged in upon registration.

Request body

string

required

The user’s email address. Stored in lowercase. Must not already be registered in the system.

password

string

required

Plain-text password. Must be at least 6 characters long. Hashed with PBKDF2-SHA512 before storage; never persisted in plain text.

Response

success

boolean

Always true on a 200 response.

user

object

The newly created user object.

Show user fields

string

UUID assigned to the user at creation.

string

The registered email address (lowercased).

role

string

Always CLIENTE for newly registered users.

creatorStore

null

Always null on registration. Populated after converting to CREADOR.

{
  "success": true,
  "user": {
    "id": "a1b2c3d4-...",
    "email": "usuario@example.com",
    "role": "CLIENTE",
    "creatorStore": null
  }
}

Cookies set

Cookie	Value	Flags
`krafta-token`	Signed JWT	HttpOnly, SameSite=lax, Secure (prod), 24 h
`krafta-role`	`CLIENTE`	SameSite=lax, 24 h

Error responses

Status	Condition
`400`	`email` or `password` field is missing from the body
`400`	Email is already registered
`400`	Password is shorter than 6 characters

Verifies credentials against the stored PBKDF2-SHA512 hash and, on success, signs a new JWT and sets the session cookies.

Request body

string

required

The registered email address.

password

string

required

The account password.

Response

success

boolean

true on a successful login.

user

object

The authenticated user object.

Show user fields

string

The user’s UUID.

string

The user’s email address.

role

string

One of CLIENTE, ADMIN, TALLER, or CREADOR.

creatorStore

object | null

The creator store profile if the user has the CREADOR role; null otherwise.

{
  "success": true,
  "user": {
    "id": "a1b2c3d4-...",
    "email": "usuario@example.com",
    "role": "CLIENTE",
    "creatorStore": null
  }
}

Cookies set

Cookie	Value	Flags
`krafta-token`	Signed JWT	HttpOnly, SameSite=lax, Secure (prod), 24 h
`krafta-role`	User role string	SameSite=lax, 24 h

Error responses

Status	Condition
`400`	`email` or `password` field is missing
`401`	Email not found or password does not match

Example

curl -X POST http://localhost:3000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "admin@example.com", "password": "yourpassword"}' \
  -c cookies.txt

POST /api/auth/logout

Terminates the current session by expiring both auth cookies. No request body is required.

Response

success

boolean

true when the cookies have been cleared.

message

string

Human-readable confirmation: "Sesión cerrada correctamente".

{
  "success": true,
  "message": "Sesión cerrada correctamente"
}

The krafta-token and krafta-role cookies are overwritten with empty values and maxAge: 0, causing browsers to immediately discard them.

GET /api/auth/me

Returns the currently authenticated user’s profile. The endpoint reads the krafta-token cookie, verifies the JWT signature and expiry, and fetches the fresh user record from the database. Unlike the login response, this endpoint performs a live database lookup so that any role changes made since the token was issued are reflected in the response.

Response

authenticated

boolean

true when a valid, unexpired token is present and the user exists.

user

object

Present only when authenticated is true.

Show user fields

string

The user’s UUID.

string

The user’s email address.

role

string

Current role as stored in the database: CLIENTE, ADMIN, TALLER, or CREADOR.

creatorStore

object | null

Creator store profile (displayName, slug, bio) if the user is a CREADOR; null otherwise.

{
  "authenticated": true,
  "user": {
    "id": "a1b2c3d4-...",
    "email": "creador@example.com",
    "role": "CREADOR",
    "creatorStore": {
      "displayName": "Estudio Luna",
      "slug": "estudio-luna",
      "bio": "Diseños minimalistas para el día a día."
    }
  }
}

When no valid cookie is present or the token has expired, the endpoint responds with HTTP 200 and { "authenticated": false } rather than a 401, so client-side session checks are always safe to make.

POST /api/auth/convert-creator

Upgrades the authenticated user from CLIENTE to the CREADOR role and creates the associated Creator and CreatorStore records. A new JWT with the updated role is re-issued and set on the response cookies. This endpoint requires a valid krafta-token cookie. Callers that are already CREADOR, ADMIN, or TALLER should not call this endpoint.

Request body

displayName

string

required

The public-facing name of the creator’s store (e.g. "Estudio Luna").

slug

string

required

A URL-friendly handle for the store. Sanitized server-side: lowercased and stripped of characters outside [a-z0-9-_]. Must be unique across all creator stores.

bio

string

A short description of the creator’s store. Optional.

Response

success

boolean

true on a successful conversion.

user

object

Updated user object reflecting the new CREADOR role.

Show user fields

string

The user’s UUID.

string

The user’s email address.

role

string

CREADOR after a successful conversion.

creatorStore

object

The newly created store profile containing displayName, slug, and bio.

{
  "success": true,
  "user": {
    "id": "a1b2c3d4-...",
    "email": "usuario@example.com",
    "role": "CREADOR",
    "creatorStore": {
      "displayName": "Estudio Luna",
      "slug": "estudio-luna",
      "bio": "Diseños minimalistas para el día a día."
    }
  }
}

Error responses

Status	Condition
`400`	`displayName` or `slug` is missing from the request body
`400`	The sanitized slug is already in use by another creator
`401`	No `krafta-token` cookie present, or the token is expired/invalid

How authentication is enforced

Both cookies are scoped to path: "/" and set with SameSite=lax. The krafta-token cookie carries the HttpOnly flag so JavaScript running in the browser cannot read it. In production (NODE_ENV === "production"), both cookies are also marked Secure, restricting transmission to HTTPS connections only.

JWT structure

Tokens use the HS256 algorithm. The payload contains:

{
  "id": "<user-uuid>",
  "email": "usuario@example.com",
  "role": "CLIENTE",
  "exp": 1720000000
}

The signature is computed with HMAC-SHA256 keyed on the JWT_SECRET environment variable. Tokens expire 24 hours after issuance. There are no refresh tokens; users must re-authenticate once a token expires.

Role-based access control

Server-side route handlers that require a specific role call requireRole(request, ["ADMIN"]) from src/lib/api-auth.js. This helper:

Reads the krafta-token cookie from the incoming request.
Verifies the JWT signature and expiry.
Checks that the decoded role claim is in the list of allowed roles.
Returns a 403 response if the check fails, or the decoded user payload if it passes.

Valid roles defined in the Prisma schema are CLIENTE, ADMIN, TALLER, and CREADOR.

Authentication

Endpoints

Authentication API: register, login, and session management

POST /api/auth/register

Request body

Response

Cookies set

Error responses

Request body

Response

Cookies set

Error responses

Example

POST /api/auth/logout

Response

GET /api/auth/me

Response

POST /api/auth/convert-creator

Request body

Response

Error responses

How authentication is enforced

JWT structure

Role-based access control

Build docs developers (and LLMs) love

Authentication

Endpoints

Documentation Index

​POST /api/auth/register

​Request body

​Response

​Cookies set

​Error responses

​POST /api/auth/login

​Request body

​Response

​Cookies set

​Error responses

​Example

​POST /api/auth/logout

​Response

​GET /api/auth/me

​Response

​POST /api/auth/convert-creator

​Request body

​Response

​Error responses

​How authentication is enforced

​Cookie security model

​JWT structure

​Role-based access control

Build docs developers (and LLMs) love

POST /api/auth/register

Request body

Response

Cookies set

Error responses

POST /api/auth/login

Request body

Response

Cookies set

Error responses

Example

POST /api/auth/logout

Response

GET /api/auth/me

Response

POST /api/auth/convert-creator

Request body

Response

Error responses

How authentication is enforced

Cookie security model

JWT structure

Role-based access control