Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shipfastai.dev/llms.txt

Use this file to discover all available pages before exploring further.

The auth API handles the complete identity lifecycle: account creation, credential-based login, JWT token management, email verification, password recovery, and OAuth sign-in via Google or GitHub. All endpoints are mounted under the /api/auth/ prefix.

​
POST /api/auth/register

Create a new user account. After registration, a verification email is sent to the provided address.
​
email
string
required
The user’s email address. Must be a valid email format and not already registered.
​
password
string
required
The user’s password in plain text. It is hashed before storage.
​
full_name
string
The user’s display name. Optional.
curl --request POST \
  --url http://localhost:8000/api/auth/register \
  --header "Content-Type: application/json" \
  --data '{
    "email": "user@example.com",
    "password": "secure-password-123",
    "full_name": "Jane Smith"
  }'
Response — UserResponse:
​
id
string
required
UUID of the newly created user.
​
email
string
required
The registered email address.
​
full_name
string
The user’s display name, if provided.
​
avatar_url
string
Profile picture URL. null for newly registered users.
​
is_active
boolean
required
Whether the account is active. true by default on registration.
​
is_verified
boolean
required
Whether the email has been verified. false until the verification link is clicked.
​
oauth_provider
string
The OAuth provider used to sign in (google, github), or null for password-based accounts.
​
subscription_status
string
required
Current subscription status (e.g., free, active, cancelled).
​
subscription_tier
string
required
Subscription tier (e.g., free, pro).
​
created_at
string
required
ISO 8601 timestamp of when the account was created.
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "user@example.com",
  "full_name": "Jane Smith",
  "avatar_url": null,
  "is_active": true,
  "is_verified": false,
  "oauth_provider": null,
  "subscription_status": "free",
  "subscription_tier": "free",
  "created_at": "2024-01-15T10:30:00Z"
}

​
POST /api/auth/login

Authenticate with email and password. Returns a JWT access token and refresh token.
​
email
string
required
The user’s registered email address.
​
password
string
required
The user’s password.
curl --request POST \
  --url http://localhost:8000/api/auth/login \
  --header "Content-Type: application/json" \
  --data '{
    "email": "user@example.com",
    "password": "secure-password-123"
  }'
Response — Token:
​
access_token
string
required
JWT access token. Valid for 30 minutes. Pass this in the Authorization header.
​
refresh_token
string
required
JWT refresh token. Use this to obtain a new access token after expiry.
​
token_type
string
required
Always "bearer".
​
user
object
The authenticated user object. See UserResponse fields above.
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "user@example.com",
    "full_name": "Jane Smith",
    "is_verified": true,
    "subscription_status": "active",
    "subscription_tier": "pro",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

​
POST /api/auth/refresh

Exchange a valid refresh token for a new access token and refresh token pair. Both tokens are rotated on every call.
​
refresh_token
string
required
A valid, unexpired refresh token previously issued by /api/auth/login or a prior /api/auth/refresh call.
curl --request POST \
  --url http://localhost:8000/api/auth/refresh \
  --header "Content-Type: application/json" \
  --data '{"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'
Response — Token (same shape as login, user field is null): 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": null
}

​
POST /api/auth/logout

Log out the current user. Because JWTs are stateless, the server does not invalidate the token — the client is responsible for discarding both tokens from storage. No request body required. 
curl --request POST \
  --url http://localhost:8000/api/auth/logout
Response: 
{
  "message": "Successfully logged out"
}

​
GET /api/auth/me

Return the profile of the currently authenticated user. Headers:
​
Authorization
string
required
Bearer <access_token>
curl --request GET \
  --url http://localhost:8000/api/auth/me \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Response — UserResponse (see fields above): 
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "user@example.com",
  "full_name": "Jane Smith",
  "avatar_url": null,
  "is_active": true,
  "is_verified": true,
  "oauth_provider": null,
  "subscription_status": "active",
  "subscription_tier": "pro",
  "created_at": "2024-01-15T10:30:00Z"
}

​
POST /api/auth/verify-email

Verify a user’s email address using the token sent to them after registration.
​
token
string
required
The verification token extracted from the link in the verification email.
curl --request POST \
  --url http://localhost:8000/api/auth/verify-email \
  --header "Content-Type: application/json" \
  --data '{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'
Response: 
{
  "message": "Email verified successfully"
}
If the email was already verified, the response is: 
{
  "message": "Email already verified"
}

​
POST /api/auth/resend-verification

Resend the verification email to a registered address. This endpoint always returns 200 regardless of whether the email is registered, to prevent email enumeration.
​
email
string
required
The email address to resend the verification link to.
curl --request POST \
  --url http://localhost:8000/api/auth/resend-verification \
  --header "Content-Type: application/json" \
  --data '{"email": "user@example.com"}'
Response: 
{
  "message": "If your email is registered, a verification link has been sent"
}

​
POST /api/auth/forgot-password

Request a password reset email. Like resend-verification, this always returns 200 to prevent email enumeration.
​
email
string
required
The email address associated with the account.
curl --request POST \
  --url http://localhost:8000/api/auth/forgot-password \
  --header "Content-Type: application/json" \
  --data '{"email": "user@example.com"}'
Response: 
{
  "message": "If your email is registered, a password reset link has been sent"
}

​
POST /api/auth/verify-reset-token

Check whether a password reset token is still valid before presenting the reset form to the user.
​
token
string
required
The password reset token from the reset email link.
curl --request POST \
  --url http://localhost:8000/api/auth/verify-reset-token \
  --header "Content-Type: application/json" \
  --data '{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'
Response: 
{
  "valid": true
}
Returns 400 with {"detail": "Invalid or expired reset token"} if the token is invalid or expired.

​
POST /api/auth/reset-password

Set a new password using a valid password reset token.
​
token
string
required
The password reset token from the reset email link.
​
new_password
string
required
The new password to set for the account.
curl --request POST \
  --url http://localhost:8000/api/auth/reset-password \
  --header "Content-Type: application/json" \
  --data '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "new_password": "new-secure-password-456"
  }'
Response: 
{
  "message": "Password reset successfully"
}

​
GET /api/auth/oauth/

Initiate an OAuth sign-in flow. Returns the authorization URL that you redirect the user to. Supported providers are google and github.
​
provider
string
required
The OAuth provider to use. Must be google or github. The provider must be configured in your backend settings.
curl --request GET \
  --url http://localhost:8000/api/auth/oauth/google
Response:
​
authorization_url
string
required
The full URL to redirect the user to in order to begin the OAuth flow.
​
state
string
required
A CSRF state token. Pass this back when handling the OAuth callback to validate the flow.
{
  "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&state=...",
  "state": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
After the user authorizes the app, the provider redirects to GET /api/auth/callback/{provider}, which exchanges the code for tokens and redirects the browser to {FRONTEND_URL}/auth/callback?access_token=...&refresh_token=....
The callback endpoint is handled automatically by the backend — you do not need to call it directly. Configure your OAuth app’s redirect URI to point to {your-backend-url}/api/auth/callback/{provider}.