Authentication API
Secure authentication endpoints for API access
Overview
The Authentication API provides secure endpoints for logging in, managing tokens, and handling user sessions. All authentication uses JWT (JSON Web Tokens) with access and refresh token rotation for maximum security.
🔐
Security First
Access tokens expire after 60 minutes. Refresh tokens expire after 30 days. All tokens are cryptographically signed and validated.
Authentication Flow
1
Login with Credentials
POST /auth/login with email and password
2
Receive Tokens
Get access_token (60 min) and refresh_token (30 days)
3
Make API Requests
Include access_token in Authorization header
4
Refresh When Expired
POST /auth/refresh with refresh_token to get new access_token
POST
/auth/login
Authenticate with email and password to receive access tokens.
Request Body
{
"email": "user@example.com",
"password": "your-secure-password"
}
Response (200 OK)
{
"success": true,
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600,
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"full_name": "John Doe",
"subscription_tier": "professional"
}
},
"meta": {
"timestamp": "2025-10-30T12:00:00Z",
"requestId": "req_login_123"
}
}
Error Response (401 Unauthorized)
{
"success": false,
"error": {
"code": "invalid_credentials",
"message": "Invalid email or password"
}
}
POST
/auth/refresh
Obtain a new access token using a valid refresh token.
Request Body
{
"refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
Response (200 OK)
{
"success": true,
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600
}
}
POST
/auth/logout
Invalidate the current access and refresh tokens.
Headers
Authorization: Bearer YOUR_ACCESS_TOKEN
Response (200 OK)
{
"success": true,
"data": {
"message": "Successfully logged out"
}
}
POST
/auth/forgot-password
Request a password reset link via email.
Request Body
{
"email": "user@example.com"
}
Response (200 OK)
{
"success": true,
"data": {
"message": "Password reset email sent"
}
}
POST
/auth/reset-password
Reset password using a reset token received via email.
Request Body
{
"token": "reset_token_from_email",
"new_password": "new-secure-password"
}
Response (200 OK)
{
"success": true,
"data": {
"message": "Password successfully reset"
}
}
GET
/auth/verify
Verify that the current access token is valid.
Headers
Authorization: Bearer YOUR_ACCESS_TOKEN
Response (200 OK)
{
"success": true,
"data": {
"valid": true,
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"subscription_tier": "professional"
},
"expires_at": "2025-10-30T13:00:00Z"
}
}
Common Error Codes
| Code | Status | Description |
|---|
| invalid_credentials | 401 | Email or password is incorrect |
| token_expired | 401 | Access token has expired, use refresh token |
| invalid_token | 401 | Token is malformed or invalid |
| account_locked | 403 | Account is locked due to security reasons |
| email_not_verified | 403 | Email address must be verified first |
| rate_limit_exceeded | 429 | Too many authentication attempts |
Best Practices
✓
Use HttpOnly Cookies (REQUIRED)
Organiko API uses HttpOnly cookies for authentication. NEVER use localStorage or sessionStorage - these are vulnerable to XSS attacks. Always set credentials: 'include' in fetch requests.
✓
Implement Token Refresh
Automatically refresh access tokens before they expire to maintain seamless user experience.
✓
Handle Token Expiration
Gracefully handle 401 responses by refreshing tokens or redirecting to login.
✓
Use HTTPS Only
Always use HTTPS in production to protect tokens in transit.
Code Example (Cookie-Based Auth)
// TypeScript/JavaScript Example with HttpOnly Cookies
async function login(email: string, password: string) {
const response = await fetch('https://api.organiko.ai/v1/auth/jwt/login', {
method: 'POST',
credentials: 'include', // CRITICAL: Receive HttpOnly cookies from server
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({ email, password }),
});
if (!response.ok) {
throw new Error('Login failed');
}
const data = await response.json();
// NO localStorage needed - tokens are stored in secure HttpOnly cookies
// Backend automatically sets cookies in the response
return data.user;
}
// Make authenticated request
async function makeAuthRequest(endpoint: string) {
const response = await fetch(`https://api.organiko.ai/v1${endpoint}`, {
credentials: 'include', // Automatically sends cookies
// NO Authorization header needed - cookies handle authentication
});
if (response.status === 401) {
// Session expired, redirect to login
window.location.href = '/auth/login';
return;
}
return response.json();
}
View More Code Examples →