The OSUS.AI Authentication API provides secure user authentication, registration, and session management with support for OAuth providers and multi-factor authentication.
https://api.osus.ai/v1/auth
All API requests require authentication via JWT tokens in the Authorization header.
Authorization: Bearer YOUR_JWT_TOKENAlways use HTTPS in production. Never expose your API tokens in client-side code.
Register a new user account.
/auth/register
| Parameter | Type | Required | Description |
|---|---|---|---|
email |
string | Yes | User's email address |
password |
string | Yes | Password (min 8 characters) |
firstName |
string | Yes | User's first name |
lastName |
string | Yes | User's last name |
phone |
string | No | Phone number (Egyptian format) |
accountType |
string | No | Account type: individual, business |
referralCode |
string | No | Referral code from existing user |
curl -X POST https://api.osus.ai/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "ahmed@example.com",
"password": "SecurePass123!",
"firstName": "Ahmed",
"lastName": "Mohamed",
"phone": "+201234567890",
"accountType": "individual"
}'{
"success": true,
"data": {
"user": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "ahmed@example.com",
"firstName": "Ahmed",
"lastName": "Mohamed",
"accountType": "individual",
"emailVerified": false,
"createdAt": "2025-01-15T10:30:00Z"
},
"tokens": {
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600
}
},
"timestamp": "2025-01-15T10:30:00Z",
"requestId": "req_123456"
}Authenticate a user and receive access tokens.
/auth/login
| Parameter | Type | Required | Description |
|---|---|---|---|
email |
string | Yes | User's email address |
password |
string | Yes | User's password |
rememberMe |
boolean | No | Extended session duration |
deviceInfo |
object | No | Device information for security |
curl -X POST https://api.osus.ai/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "ahmed@example.com",
"password": "SecurePass123!",
"rememberMe": true,
"deviceInfo": {
"type": "mobile",
"platform": "iOS",
"version": "17.2"
}
}'{
"success": true,
"data": {
"user": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "ahmed@example.com",
"firstName": "Ahmed",
"lastName": "Mohamed",
"loyaltyTier": "gold",
"lastLogin": "2025-01-15T10:30:00Z"
},
"tokens": {
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600
},
"mfaRequired": false
},
"timestamp": "2025-01-15T10:30:00Z",
"requestId": "req_123457"
}Refresh an expired access token using a refresh token.
/auth/refresh
| Parameter | Type | Required | Description |
|---|---|---|---|
refreshToken |
string | Yes | Valid refresh token |
curl -X POST https://api.osus.ai/v1/auth/refresh \
-H "Content-Type: application/json" \
-d '{
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}'Authenticate using third-party OAuth providers.
/auth/oauth/{provider}
curl -X POST https://api.osus.ai/v1/auth/oauth/google \
-H "Content-Type: application/json" \
-d '{
"accessToken": "google_access_token_here",
"idToken": "google_id_token_here"
}'| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | INVALID_CREDENTIALS |
Invalid email or password |
| 400 | EMAIL_ALREADY_EXISTS |
Email already registered |
| 400 | WEAK_PASSWORD |
Password doesn't meet requirements |
| 401 | INVALID_TOKEN |
JWT token is invalid or expired |
| 401 | MFA_REQUIRED |
Multi-factor authentication required |
| 429 | RATE_LIMIT_EXCEEDED |
Too many authentication attempts |