Userverse uses two complementary authentication mechanisms. HTTP Basic Auth is the entry point — you use it to register or log in and receive a JWT token pair. From that point on, you pass the access token as a Bearer token to authenticate every subsequent request.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/SoftwareVerse/userverse/llms.txt
Use this file to discover all available pages before exploring further.
Authentication methods
Basic Auth
Pass your email and password in the
Authorization header to create an account or log in. Userverse validates your credentials and returns a JWT token pair.JWT Bearer
Pass an access token in the
Authorization: Bearer header to call protected endpoints. Tokens are signed with HS256 and expire based on your configuration.How the two methods relate
The two methods are used in sequence. Basic Auth is only needed at the edges of a session — to create an account, log in, or reset a password. All other calls use the JWT access token returned by those endpoints.Register or log in with Basic Auth
Call
POST /user/create or PATCH /user/login using HTTP Basic Auth. Your email is the username and your password is the password.Receive a token pair
A successful request returns an
access_token and a refresh_token, along with their expiration timestamps.Call protected endpoints with the access token
Include
Authorization: Bearer <access_token> in the header of every subsequent request.Token types
Userverse issues two tokens on login.| Token | Purpose | Default lifetime |
|---|---|---|
access_token | Authenticates requests to protected endpoints | 30 minutes (jwt.TIMEOUT) |
refresh_token | Obtains a new token pair when the access token expires | 60 minutes (jwt.REFRESH_TIMEOUT) |
config.json under the jwt key. See the configuration reference for details.
Standard error responses
| Status | Meaning | Common cause |
|---|---|---|
401 Unauthorized | Missing or malformed credentials | No Authorization header, wrong Basic Auth format, or expired access token |
403 Forbidden | Invalid credentials or wrong token type | Wrong password, invalid JWT signature, or using a refresh token where an access token is required |
A
401 on a JWT-protected endpoint generally means the token is missing or has expired. A 403 means the token was present and parseable but was rejected — for example, because the signature is wrong or the token type is incorrect.Next steps
Basic Auth
See which endpoints require Basic Auth, how to format the header, and curl examples.
JWT authentication
Learn how to pass tokens, understand the token response model, and handle common errors.