Authentication Guide

LangMart supports multiple authentication methods to suit different use cases. This guide covers all the ways you can authenticate with the platform.

Authentication Overview

OAuth Login

OAuth is the recommended authentication method for web users. It provides a seamless login experience without managing passwords.

Supported Providers

How OAuth Works

1. Initiate Login - Click "Sign in with Google" or "Sign in with GitHub" on the login page
2. Authorize - You're redirected to the provider to grant LangMart access
3. Callback - After authorization, you're redirected back to LangMart
4. Session Created - A session is established with your user account

OAuth Flow Diagram

┌──────────┐     ┌──────────────┐     ┌────────────┐
│  User    │────>│   LangMart   │────>│  Provider  │
│ Browser  │     │   Web App    │     │  (Google/  │
│          │     │              │     │   GitHub)  │
└──────────┘     └──────────────┘     └────────────┘
     │                  │                    │
     │ 1. Click Login   │                    │
     │─────────────────>│                    │
     │                  │ 2. Redirect        │
     │                  │───────────────────>│
     │                  │                    │
     │<─────────────────────────────────────│
     │         3. User authorizes           │
     │                  │                    │
     │                  │<───────────────────│
     │                  │   4. OAuth token   │
     │<─────────────────│                    │
     │   5. Session established             │

First-Time OAuth Users

When you log in with OAuth for the first time:

1. A new user account is created using your OAuth profile
2. You're assigned to a default organization
3. An API key is automatically generated for your session
4. Your display name and avatar are synced from your OAuth provider

Linking Multiple OAuth Providers

Currently, each OAuth provider creates a separate account. If you need to access the same account from multiple providers, contact support.

Email Registration

For users who prefer traditional email-based authentication:

Registration

1. Navigate to the Register option on the login page
2. Enter your email address and create a password
3. Verify your email through the confirmation link
4. Log in with your credentials

Password Requirements

• Minimum 8 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one number

Password Reset

1. Click "Forgot Password" on the login page
2. Enter your email address
3. Check your email for a reset link
4. Create a new password

Guest Access

Guest access lets you explore LangMart without creating an account.

Starting a Guest Session

1. Visit https://langmart.ai
2. Click Continue as Guest
3. A temporary session is created automatically

Guest Limitations

Converting Guest to Account

To convert your guest session to a full account:

1. Click Sign Up in the top navigation
2. Choose OAuth or email registration
3. Your guest session will be migrated to your new account

Note: Guest session data is not automatically preserved. Create an account before doing important work.

JWT Tokens

LangMart uses JSON Web Tokens (JWT) for session management.

Token Structure

Header.Payload.Signature

Token Lifecycle

Token Expiration

Automatic Token Refresh

The web application automatically refreshes tokens:

1. When a request fails with 401 Unauthorized
2. Proactively before token expiration
3. On page reload (validates stored session)

Manual Token Refresh

For API clients, you can refresh tokens manually:

curl -X POST https://api.langmart.ai/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

API Key Authentication

API keys provide programmatic access to the LangMart API.

Creating API Keys

1. Go to Settings > API Keys
2. Click Create New Key
3. Enter a descriptive name
4. Copy the key immediately (shown only once)

API Key Format

sk-langmart-xxxxxxxxxxxxxxxxxxxxxxxx

• Prefix: sk-langmart-
• Random characters: 24+ alphanumeric characters

Using API Keys

Include your API key in the Authorization header:

curl -X GET https://api.langmart.ai/v1/models \
  -H "Authorization: Bearer sk-langmart-your-key-here"

API Key Scopes

Currently, all API keys have full access to your account. Fine-grained permissions are planned for a future release.

Key Management Best Practices

Revoking API Keys

To revoke an API key:

1. Go to Settings > API Keys
2. Find the key you want to revoke
3. Click the Delete button
4. Confirm the deletion

Warning: Revoking a key immediately invalidates it. Any applications using that key will stop working.

Security Best Practices

Do

• Use OAuth for web applications when possible
• Store API keys in environment variables
• Rotate API keys periodically
• Use HTTPS for all API calls
• Log out of shared computers

Don't

• Share API keys in public repositories
• Hardcode API keys in source code
• Share API keys in chat or email
• Use the same API key for multiple environments
• Ignore security alerts from LangMart

Session Management

Viewing Active Sessions

1. Go to Settings > Security
2. View all active sessions with device/location info
3. Revoke suspicious sessions if needed

Logging Out

To log out:

1. Click your profile icon in the top navigation
2. Select Logout
3. Your session is invalidated immediately

Logging Out Everywhere

To log out from all devices:

1. Go to Settings > Security
2. Click Log Out All Sessions
3. All active sessions are invalidated

Troubleshooting Authentication

"Invalid credentials" Error

• Verify your email and password
• Check for caps lock
• Try resetting your password

OAuth Redirect Issues

• Clear browser cookies and try again
• Disable browser extensions that may block redirects
• Try a different browser

API Key Not Working

• Verify the key was copied completely
• Check that the key hasn't been revoked
• Ensure you're using Bearer token format

Session Expired

• Refresh the page to trigger automatic token refresh
• If that fails, log in again
• Check that your browser accepts cookies

API Endpoints Reference