Auth API

Authentication is the first step for all protected routes.

API call order

1. POST /signup
2. POST /verify
3. POST /login to receive tokens
4. Use access_token in protected routes
5. POST /refresh when access token expires

Shared request setup is documented once in API index.

Signup

POST /signup

Register a new user and send an activation email.

Creates a user account and emails an activation link containing a one-time activation code.

Parameters:

Name	Type	Description	Default
request	SignupRequest	Signup payload with user details and password.	required

Returns:

Type	Description
SignupResponse	Created user summary.

Raises:

Type	Description
HTTPException	400 if invalid or duplicate signup data.

Usage

resp = requests.post(
    f"{BASE_URL}/signup",
    json={
        "email": "astro.user@example.com",
        "password": "StrongPassword123!",
        "first_name": "Astro",
        "last_name": "User",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Explanation

Creates an inactive user account and triggers an activation email.

Notes

• Verification is required before login.
• Email must be unique.

Verify account

POST /verify

Verify account activation using the activation code.

Marks the user as active if the provided code matches and clears the code.

Parameters:

Name	Type	Description	Default
request	VerifyRequest	Verification payload with email and activation code.	required

Returns:

Type	Description
dict	Confirmation message.

Raises:

Type	Description
HTTPException	404 if user not found; 400 if activation code is invalid.

Usage

resp = requests.post(
    f"{BASE_URL}/verify",
    json={
        "email": "astro.user@example.com",
        "activation_code": "123456",
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Explanation

Activates the account using the code sent by email.

Notes

• Call this before POST /login.
• Use POST /resend-activation if the code is missing/expired.

Login

POST /login

Authenticate a user and issue JWT tokens.

Validates the provided credentials, ensures the account is active, and returns an access and refresh token.

Parameters:

Name	Type	Description	Default
request	LoginRequest	Login credentials payload.	required

Returns:

Type	Description
LoginResponse	Access and refresh tokens.

Raises:

Type	Description
HTTPException	401 if invalid credentials or user not found; 403 if account not activated.

Usage

resp = requests.post(
    f"{BASE_URL}/login",
    json={
        "email": "astro.user@example.com",
        "password": "StrongPassword123!",
    },
    timeout=30,
)
resp.raise_for_status()
tokens = resp.json()
ACCESS_TOKEN = tokens["access_token"]
REFRESH_TOKEN = tokens["refresh_token"]
print(tokens)

Explanation

Returns JWT tokens used by all protected APIs.

Notes

• Add Authorization: Bearer <access_token> to protected requests.
• Keep refresh_token for access token renewal.

Refresh access token

POST /refresh

Exchange a refresh token for a new access token.

Decodes and validates the provided refresh token and returns a new access token if the token and user are valid.

Parameters:

Name	Type	Description	Default
request	RefreshRequest	Refresh token payload.	required

Returns:

Type	Description
RefreshResponse	Fresh access token.

Raises:

Type	Description
HTTPException	401 if invalid refresh token or user not found.

Usage

resp = requests.post(
    f"{BASE_URL}/refresh",
    json={"refresh_token": REFRESH_TOKEN},
    timeout=30,
)
resp.raise_for_status()
ACCESS_TOKEN = resp.json()["access_token"]
print(resp.json())

Explanation

Issues a new access token without re-entering credentials.

Notes

• Keep using the same header format with the new token.
• Use when protected endpoints return auth-expired errors.

Resend activation email

POST /resend-activation

Resend the account activation email.

Generates a new activation code (if the account is not yet active) and sends the activation email again.

Parameters:

Name	Type	Description	Default
request	ResendActivationRequest	Email address for the account.	required

Returns:

Type	Description
dict	Confirmation message.

Raises:

Type	Description
HTTPException	404 if user is not found.

Usage

resp = requests.post(
    f"{BASE_URL}/resend-activation",
    json={"email": "astro.user@example.com"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Explanation

Sends a new activation code for unverified accounts.

Notes

• Use only before successful verification.

Token usage helper

headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"}

Full API reference

For exhaustive schema details, use Swagger API.