Skip to main content

​
Overview

KeyBox uses JWT (JSON Web Tokens) for authenticating API requests. Protected endpoints require a valid JWT token in the Authorization header.

​
Authentication Methods

KeyBox supports two authentication methods:
  1. Email/Password Authentication - Standard signup and login
  2. Google OAuth - OAuth-based authentication with Google

​
Signup

Create a new user account.

​
Endpoint

POST /auth/signup

​
Request Body

​
name
string
required
User’s full name
​
email
string
required
User’s email address
​
password
string
required
Password (minimum 6 characters)
​
confirm_password
string
required
Password confirmation (must match password)

​
Response

​
message
string
Success message
​
userId
string
The ID of the created user

​
Example Request

curl -X POST https://your-keybox-server.com/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "securepass123",
    "confirm_password": "securepass123"
  }'

​
Example Response

{
  "message": "Signup successful",
  "userId": "60f7b3b3e6b3a72e8c8e4a1a"
}

​
Login

Authenticate and receive a JWT token.

​
Endpoint

POST /auth/login

​
Request Body

​
email
string
required
User’s email address
​
password
string
required
User’s password

​
Response

​
message
string
Success message
​
token
string
JWT authentication token (expires in 30 minutes)
​
userId
string
The user’s ID
​
role
string
The user’s role (e.g., “DEVELOPER”)

​
Example Request

curl -X POST https://your-keybox-server.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepass123"
  }'

​
Example Response

{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "60f7b3b3e6b3a72e8c8e4a1a",
  "role": "DEVELOPER"
}

​
Using Authentication Tokens

Once you have a JWT token, include it in the Authorization header for protected endpoints: 
Authorization: Bearer <your-jwt-token>

​
Example Authenticated Request

curl -X GET https://your-keybox-server.com/dashboard \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Token Expiration

JWT tokens expire after 30 minutes. Implement token refresh logic in your application.
When a token expires, you’ll receive a 401 Unauthorized response: 
{
  "message": "Unauthorized",
  "error": "jwt expired"
}

​
Google OAuth

KeyBox also supports Google OAuth authentication. The OAuth routes are configured at the root level:
  • Initiate OAuth flow through your KeyBox instance
  • User is redirected to Google for authentication
  • Upon success, user is redirected back with authentication established
Users who sign up with Google OAuth cannot use password-based login and vice versa.

​
Error Responses

​
Missing Token

{
  "message": "No token provided"
}

​
Invalid Token Format

{
  "message": "Invalid token format"
}

​
Invalid Credentials

{
  "message": "Invalid credentials"
}

​
Google OAuth Account

{
  "message": "This account uses Google sign-in. Please login with Google."
}

​
Best Practices

Secure Storage

Store JWT tokens securely (e.g., httpOnly cookies, secure storage)

Token Refresh

Implement automatic token refresh before expiration

HTTPS Only

Always use HTTPS in production to protect tokens

Error Handling

Handle 401 errors gracefully and redirect to login

Build docs developers (and LLMs) love

Get started for freeTalk to us