Authentication Guide

LangMart supports three ways to authenticate. This guide covers each of them, and only describes what the platform actually does today.

Authentication Overview

There is no email-and-password sign-up. Every human account is created through an OAuth provider.

OAuth Login

OAuth is the only way to create a LangMart account. You never set a LangMart password; your identity provider handles that.

Supported Providers

How OAuth Works

1. Initiate Login - On the LangMart home page, choose Google, GitHub or Microsoft
2. Authorize - You are redirected to the provider to grant LangMart access
3. Callback - After authorization, you are redirected back to LangMart
4. Session Created - A session key is issued and stored in your browser

OAuth Flow Diagram

┌──────────┐     ┌──────────────┐     ┌────────────┐
│  User    │────>│   LangMart   │────>│  Provider  │
│ Browser  │     │   Web App    │     │  (Google/  │
│          │     │              │     │   GitHub/  │
└──────────┘     └──────────────┘     │ Microsoft) │
     │                  │             └────────────┘
     │ 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 are assigned to a default organization
3. A session key is automatically generated for your browser
4. Your display name and avatar are synced from your OAuth provider

Using More Than One Provider

Accounts are matched by email address. If you sign in with GitHub using the same email you first used with Google, you land in the same account, and the second provider is linked to it. You can then sign in with either.

Guest Access

Guest access lets you explore LangMart without creating an account.

Starting a Guest Session

You do not have to do anything. When you visit https://langmart.ai without being signed in, a guest session is created for you automatically.

A guest session lasts 90 days and the window slides: each visit extends it.

Guest Limitations

Converting Guest to Account

Sign in with Google, GitHub or Microsoft from the home page. Your guest session is replaced by a full account session.

Note: Guest session data is not carried over. Create an account before doing important work.

Session Keys

Signing in through OAuth issues a session key, not a JWT. It has the prefix sk-session- and is stored by your browser; the web app sends it on every request.

There is no refresh token and no refresh endpoint. Expiry means a fresh OAuth sign-in.

API Key Authentication

API keys provide programmatic access to the LangMart API.

Creating API Keys

1. Go to the API Keys page
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 the API Keys page
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

Logging Out

1. Click your profile icon in the top navigation
2. Select Logout
3. Your session key is revoked immediately, on every LangMart site that shares it

Troubleshooting Authentication

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

Session keys last 30 days and are not refreshed. Sign in again with your OAuth provider.

API Endpoints Reference

Note that the guest and validate endpoints are served at /auth/…, without the /v1 prefix.