Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Andr21Da16/Quikko/llms.txt

Use this file to discover all available pages before exploring further.

The Auth API manages user identity in Quikko. It issues JWT access and refresh tokens on registration and login, and provides endpoints to query account state, update passwords, change plans, and delete accounts. All responses use the standard JSON envelope — { "success": true, "data": {...}, "error": null } — except empty-success operations where data is null.
The user’s plan (free or pro) is not embedded in the JWT. It is read from the database on every protected operation, so plan changes take effect immediately without requiring a token refresh.

​
POST /api/v1/auth/register

POST /api/v1/auth/register Creates a new user account with the Free plan and immediately issues a JWT access/refresh token pair. Rate limited per IP using the AUTH_RATE_LIMIT_PER_MIN environment variable.

​
Request body

​
email
string
required
A valid email address. Must be unique — returns 409 AUTH_EMAIL_TAKEN if already registered.
​
password
string
required
Account password. Minimum 8 characters.

​
Response — 201 Created

​
accessToken
string
Short-lived JWT used in the Authorization: Bearer header for protected endpoints.
​
refreshToken
string
Long-lived token used to obtain a new access token via POST /api/v1/auth/refresh.
​
user
object
The newly created user record.

​
Error codes

HTTPCodeWhen
400VALIDATION_ERRORMissing or malformed fields
409AUTH_EMAIL_TAKENEmail already registered
429RATE_LIMIT_EXCEEDEDToo many requests from this IP
curl -s -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "securePass1"}'

​
POST /api/v1/auth/login

POST /api/v1/auth/login Authenticates an existing user and returns a fresh token pair. To prevent user enumeration, the server returns the same AUTH_INVALID_CREDENTIALS error whether the email does not exist or the password is wrong. Rate limited per IP separately from registration (LOGIN_RATE_LIMIT_PER_MIN).

​
Request body

​
email
string
required
The account’s email address.
​
password
string
required
The account’s password.

​
Response — 200 OK

​
accessToken
string
Short-lived JWT for authenticated requests.
​
refreshToken
string
Long-lived token for obtaining new access tokens.
​
user
object
The authenticated user.

​
Error codes

HTTPCodeWhen
400VALIDATION_ERRORMissing or malformed fields
401AUTH_INVALID_CREDENTIALSWrong email or wrong password (indistinguishable)
429RATE_LIMIT_EXCEEDEDToo many login attempts from this IP
curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "securePass1"}'

​
POST /api/v1/auth/refresh

POST /api/v1/auth/refresh Exchanges a valid refresh token for a new access token. Only accessToken is meaningful in the response — refreshToken is omitted (empty string with omitempty) and user is serialized with empty fields. The refresh token itself is not rotated. No rate limit is applied to this endpoint.

​
Request body

​
refreshToken
string
required
A refresh token obtained from a previous register or login call.

​
Response — 200 OK

​
accessToken
string
A new short-lived JWT. The refresh token itself is not rotated.
The refreshToken field is omitted from the response (Go omitempty drops empty strings). The user object is serialized with empty fields — clients should ignore it on this endpoint.

​
Error codes

HTTPCodeWhen
400VALIDATION_ERRORMissing refreshToken field
401AUTH_TOKEN_EXPIREDRefresh token has expired — user must log in again
401AUTH_TOKEN_INVALIDToken is malformed or tampered
curl -s -X POST http://localhost:8080/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "<your-refresh-token>"}'

​
GET /api/v1/auth/me

GET /api/v1/auth/me Returns the core profile of the currently authenticated user. Requires a valid Authorization: Bearer header.

​
Response — 200 OK

​
id
string
MongoDB ObjectID hex string.
​
email
string
The account email address.
​
plan
string
Current plan — "free" or "pro".
curl -s http://localhost:8080/api/v1/auth/me \
  -H "Authorization: Bearer <access-token>"

​
GET /api/v1/auth/me/summary

GET /api/v1/auth/me/summary Returns enriched account info including plan limits and aggregate usage stats. Used by the dashboard header and sidebar. Requires a valid Bearer token.

​
Response — 200 OK

​
email
string
The account email address.
​
plan
string
Current plan — "free" or "pro".
​
createdAt
string
ISO 8601 timestamp of account creation.
​
activeUrlsCount
integer
Number of URLs currently in the isActive: true state.
​
activeUrlsLimit
integer | null
Maximum active URLs allowed by the current plan. null for Pro (unlimited).
​
totalClicks
integer
Sum of totalClicks across all of the user’s URLs (approximate, fire-and-forget counter).
curl -s http://localhost:8080/api/v1/auth/me/summary \
  -H "Authorization: Bearer <access-token>"

​
PATCH /api/v1/auth/me/plan

PATCH /api/v1/auth/me/plan Changes the authenticated user’s plan. Returns the updated user object.
This endpoint is available to any authenticated user without payment validation — it is a testing convenience while Quikko does not yet have a payment gateway. In a production billing flow this would be restricted to privileged roles or a Stripe webhook.

​
Request body

​
plan
string
required
Target plan. Must be "free" or "pro".

​
Response — 200 OK

​
id
string
MongoDB ObjectID hex string.
​
email
string
The account email.
​
plan
string
The newly applied plan — "free" or "pro".
curl -s -X PATCH http://localhost:8080/api/v1/auth/me/plan \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"plan": "pro"}'

​
PATCH /api/v1/auth/me/password

PATCH /api/v1/auth/me/password Changes the authenticated user’s password. The current password must be provided and verified before the update is applied. Returns an empty-success response (data: null).

​
Request body

​
currentPassword
string
required
The user’s existing password for identity verification.
​
newPassword
string
required
The replacement password. Minimum 8 characters.

​
Response — 200 OK

Returns the standard envelope with data: null. No payload is included on success.

​
Error codes

HTTPCodeWhen
400VALIDATION_ERRORMissing fields or newPassword too short
401AUTH_INVALID_CREDENTIALScurrentPassword does not match the stored hash
401AUTH_TOKEN_INVALIDBearer token is missing or invalid
curl -s -X PATCH http://localhost:8080/api/v1/auth/me/password \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword": "oldPass123", "newPassword": "newSecurePass1"}'

​
DELETE /api/v1/auth/me

DELETE /api/v1/auth/me Permanently deletes the authenticated account and all associated data. Requires password confirmation for security. Cascade behavior: The service iterates every URL owned by the user, purges each short code from the Redis redirect cache, deletes all URLs from MongoDB, and finally removes the user record. Historical click data in InfluxDB is not deleted (out of scope).

​
Request body

​
password
string
required
The account’s current password for deletion confirmation.

​
Response — 200 OK

Returns the standard envelope with data: null.

​
Error codes

HTTPCodeWhen
400VALIDATION_ERRORMissing password field
401AUTH_INVALID_CREDENTIALSPassword is incorrect
401AUTH_TOKEN_INVALIDBearer token is missing or invalid
This action is irreversible. All URLs, custom aliases, and account settings are permanently removed. InfluxDB click history is retained but becomes orphaned.
curl -s -X DELETE http://localhost:8080/api/v1/auth/me \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"password": "securePass1"}'

Build docs developers (and LLMs) love

Get started for freeTalk to us