How Authentication Works

Learn how authentication works in AppGram, including user registration, login, session management, OAuth, and API keys.

Authentication Overview

AppGram uses Supabase Auth (powered by GoTrue) for secure user authentication. All authentication operations are handled through our backend API, which communicates with Supabase to manage users, sessions, and security.

User Registration

When a user registers, the following happens:

1. Supabase SignUp: A new user account is created in Supabase Auth with email and password
2. Email Confirmation: If email confirmation is enabled, the user receives a confirmation email. The account is not fully active until they click the confirmation link.
3. User Record: A corresponding user record is created in our database with the same ID as the Supabase user
4. Session Return: If email confirmation is disabled, a session is returned immediately with access and refresh tokens

User Login

Login uses email and password authentication via Supabase:

POST /api/v1/auth/login
{
  "email": "user@example.com",
  "password": "securepassword"
}

On successful login:

• Supabase verifies credentials and returns a session
• A user record is created in our database if it doesn't exist
• The last_seen_at timestamp is updated
• Returns: access_token, refresh_token, and expires_in

Session Management

Sessions are managed using JWT tokens:

• Access Token: Short-lived token (1 hour) used for API authentication
• Refresh Token: Long-lived token (30 days) used to obtain new access tokens
• Token Refresh: Call POST /api/v1/auth/refresh with the refresh token when the access token expires

Logout

To log out and invalidate the session:

POST /api/v1/auth/logout
Authorization: Bearer 

This invalidates the session in Supabase, preventing further use of the tokens.

Password Reset

Users can request a password reset email:

POST /api/v1/auth/forgot-password
{
  "email": "user@example.com"
}

A password reset email is sent with a secure link. The link expires after a configurable time.

OAuth Authentication

AppGram supports OAuth login with third-party providers:

• Google
• GitHub
• Slack
• Linear
• Jira

The OAuth flow:

1. Call GET /api/v1/auth/oauth/url?provider=google to get the authorization URL
2. Redirect the user to the provider's consent screen
3. After authorization, the user is redirected to your callback URL
4. The callback includes a code that can be exchanged for a session

API Keys

Organizations can create API keys for programmatic access:

POST /api/v1/organizations/:id/api-keys
{
  "name": "MCP Server",
  "scopes": ["helpcenter:read", "helpcenter:write"]
}

API Key features:

• Prefix identification: All keys start with ba_
• Secure hashing: Keys are stored as SHA256 hashes, never in plain text
• Scope-based permissions: Control what each key can access
• Rate limiting: Default 1000 requests per hour
• Optional expiration: Set expiry dates for temporary access

Security Features

• Row Level Security (RLS): Database access is restricted by user identity
• JWT Validation: All API requests validate the JWT token signature
• Token Expiration: Access tokens expire after 1 hour
• Secure Password Storage: Passwords are hashed and salted by Supabase
• Email Verification: Optional email confirmation for new accounts

Common Errors