Authentication Endpoints The Authentication API provides endpoints for user registration, login, token management, and OAuth integration. All authentication uses JWT tokens with optional OAuth providers.
Base URL https://clipron.com/api/auth Register User Create a new user account with email and password.
curl -X POST "https://clipron.com/api/auth/register" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] ", "password": "SecurePassword123!", "name": "John Doe" }'
Request Body Field Type Required Description emailstring Yes Valid email address passwordstring Yes Password (min 8 chars, must include uppercase, lowercase, number) namestring Yes User’s full name companystring No Company or organization name
Response Success (201)
Error (400)
{ "user" : { "id" : "user_clp_1234567890" , "email" : "[email protected] " , "name" : "John Doe" , "company" : null , "role" : "free" , "created_at" : "2024-06-18T10:30:00Z" , "email_verified" : false }, "message" : "User created successfully. Please check your email for verification." } { "error" : { "code" : "VALIDATION_ERROR" , "message" : "Invalid input data" , "details" : { "email" : "Email already exists" , "password" : "Password must contain at least one uppercase letter" } } } Login Authenticate user and receive JWT tokens.
curl -X POST "https://clipron.com/api/auth/login" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "[email protected] &password=SecurePassword123!"
Request Body (Form Data) Field Type Required Description usernamestring Yes User’s email address passwordstring Yes User’s password
Response Success (200)
Error (401)
Account Locked (423)
{ "access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." , "refresh_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." , "token_type" : "bearer" , "expires_in" : 1800 , "user" : { "id" : "user_clp_1234567890" , "email" : "[email protected] " , "name" : "John Doe" , "role" : "free" , "credit_balance" : 50 } } { "error" : { "code" : "INVALID_CREDENTIALS" , "message" : "Invalid email or password" } } { "error" : { "code" : "ACCOUNT_LOCKED" , "message" : "Account temporarily locked due to multiple failed login attempts" , "details" : { "locked_until" : "2024-06-18T11:00:00Z" , "remaining_minutes" : 15 } } } Refresh Token Generate new access token using refresh token.
curl -X POST "https://clipron.com/api/auth/refresh" \ -H "Content-Type: application/json" \ -H "Cookie: refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Response Success (200)
Error (401)
{ "access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." , "refresh_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." , "token_type" : "bearer" , "expires_in" : 1800 } { "error" : { "code" : "INVALID_REFRESH_TOKEN" , "message" : "Refresh token is invalid or expired" } } Logout Invalidate current session and tokens.
curl -X POST "https://clipron.com/api/auth/logout" \ -H "Authorization: Bearer <access_token>"
Response { "message" : "Successfully logged out" } Google OAuth Initiate Google OAuth Redirect user to Google for authentication.
GET https://clipron.com/api/auth/google This endpoint redirects the user to Google’s OAuth consent screen.
Google OAuth Callback Handle Google OAuth callback (internal use).
GET https://clipron.com/api/auth/google/callback?code= < auth_cod e >& state= < stat e > This endpoint is called by Google after user authorization and returns JWT tokens.
GitHub OAuth Initiate GitHub OAuth Redirect user to GitHub for authentication.
GET https://clipron.com/api/auth/github GitHub OAuth Callback Handle GitHub OAuth callback (internal use).
GET https://clipron.com/api/auth/github/callback?code= < auth_cod e >& state= < stat e > Password Reset Request Password Reset Send password reset email to user.
curl -X POST "https://clipron.com/api/auth/password-reset" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] " }'
Request Body Field Type Required Description emailstring Yes Email address of account to reset
Response { "message" : "If an account with this email exists, a password reset link has been sent." } Confirm Password Reset Reset password using token from email.
curl -X POST "https://clipron.com/api/auth/password-reset/confirm" \ -H "Content-Type: application/json" \ -d '{ "token": "reset_token_from_email", "new_password": "NewSecurePassword123!" }'
Request Body Field Type Required Description tokenstring Yes Reset token from email new_passwordstring Yes New password (same requirements as registration)
Response Success (200)
Error (400)
{ "message" : "Password reset successfully" } { "error" : { "code" : "INVALID_TOKEN" , "message" : "Password reset token is invalid or expired" } } Email Verification Resend Verification Email Send new email verification link.
curl -X POST "https://clipron.com/api/auth/verify-email/resend" \ -H "Authorization: Bearer <access_token>"
Verify Email Confirm email address using token from email.
GET https://clipron.com/api/auth/verify-email?token= < verification_toke n > This endpoint is typically accessed by clicking the link in the verification email.
Error Codes Code HTTP Status Description VALIDATION_ERROR400 Request validation failed EMAIL_EXISTS400 Email already registered INVALID_CREDENTIALS401 Wrong email or password INVALID_TOKEN401 JWT token invalid or expired INVALID_REFRESH_TOKEN401 Refresh token invalid EMAIL_NOT_VERIFIED403 Email verification required ACCOUNT_LOCKED423 Account temporarily locked RATE_LIMIT_EXCEEDED429 Too many requests
Security Features Rate Limiting
Limit : 5 failed attempts per 15 minutesLockout : 15 minutes after 5 failuresProgressive : Longer lockouts for repeated failures
Limit : 3 registrations per IP per hourEmail : 1 registration per email addressVerification : Required within 24 hours
Limit : 3 reset requests per email per hourToken expiry : 1 hourSingle use : Tokens can only be used once Token Security
Access Tokens
Lifetime : 30 minutesAlgorithm : HS256Claims : User ID, email, role, expiration
Refresh Tokens
Lifetime : 7 daysStorage : HTTP-only secure cookiesRotation : New token issued on each refresh Security Note : Always use HTTPS in production. Store refresh tokens securely and implement proper token rotation to maintain security.