Skip to main content
Gitflare uses Better Auth for authentication, providing secure session management and multiple authentication methods. All authentication endpoints are available under /api/auth.

​
Authentication methods

Gitflare supports the following authentication methods:
  • Email and password authentication
  • Session-based authentication with secure cookies
  • Personal access tokens for Git operations

​
Base URL

All authentication endpoints are relative to your Gitflare instance: 
https://your-gitflare-instance.com/api/auth

​
Sign up

Create a new user account with email and password. 
curl -X POST https://your-gitflare-instance.com/api/auth/sign-up/email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123",
    "name": "Jane Doe",
    "username": "janedoe"
  }'

​
Request body

​
email
string
required
User’s email address. Must be a valid email format.
​
password
string
required
User’s password. Must be at least 8 characters long.
​
name
string
required
User’s display name. Must be at least 2 characters long.
​
username
string
required
Unique username for the user. Must be at least 3 characters long. This username will be used in repository URLs (e.g., username/repo).

​
Response

​
user
object
The created user object.
​
session
object
Session information for the authenticated user.

​
Sign in

Authenticate an existing user with email and password. 
curl -X POST https://your-gitflare-instance.com/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123"
  }'

​
Request body

​
email
string
required
User’s email address.
​
password
string
required
User’s password.

​
Response

Returns the same user and session structure as sign up.

​
Get session

Retrieve the current authenticated user’s session information. 
curl https://your-gitflare-instance.com/api/auth/get-session \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN"

​
Response

​
user
object
The authenticated user object with all user properties.
​
session
object
Current session information including token and expiration.
Returns null if no active session exists.

​
Sign out

End the current user session. 
curl -X POST https://your-gitflare-instance.com/api/auth/sign-out \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN"

​
Response

​
success
boolean
Indicates whether the sign-out was successful.

​
Update user

Update the authenticated user’s profile information. 
curl -X POST https://your-gitflare-instance.com/api/auth/update-user \
  -H "Content-Type: application/json" \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
  -d '{
    "name": "Jane Smith"
  }'

​
Request body

​
name
string
User’s display name. Must be at least 2 characters.
Username and email cannot be changed after account creation.

​
Response

Returns the updated user object.

​
Authentication flow

Gitflare uses session-based authentication with secure HTTP-only cookies:
  1. Sign up or sign in: User provides credentials via POST request
  2. Session creation: Server creates a session and sets an HTTP-only cookie
  3. Authenticated requests: Browser automatically includes the session cookie
  4. Session validation: Server validates the session on each request
  5. Sign out: Session is invalidated and cookie is cleared

​
Security features

  • HTTP-only cookies: Session tokens are stored in HTTP-only cookies, preventing XSS attacks
  • Secure cookies: Cookies are only transmitted over HTTPS in production
  • Password hashing: Passwords are securely hashed using industry-standard algorithms
  • Session expiration: Sessions automatically expire after a period of inactivity

​
Using authentication in your application

​
With the Better Auth client

Gitflare uses the Better Auth React client for seamless authentication: 
import { authClient } from '@/lib/auth-client';

// Sign up
await authClient.signUp.email({
  email: '[email protected]',
  password: 'securepassword123',
  name: 'Jane Doe',
  username: 'janedoe',
});

// Sign in
await authClient.signIn.email({
  email: '[email protected]',
  password: 'securepassword123',
});

// Get session
const { data } = await authClient.getSession();

// Sign out
await authClient.signOut();

​
For Git operations

For Git operations (push, pull, clone), use personal access tokens instead of password authentication: 
git clone https://username:[email protected]/owner/repo.git

​
Error responses

Authentication endpoints return standard HTTP error codes:
​
error
object
Error information when a request fails.

​
Common error codes

  • 400 Bad Request: Invalid request parameters or validation errors
  • 401 Unauthorized: Invalid credentials or expired session
  • 409 Conflict: Email or username already exists (during sign up)
  • 500 Internal Server Error: Server-side error

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us