What is API Authentication?

API Authentication verifies your identity when making requests to CampusMindAI's backend services. After obtaining an Azure AD token, you exchange it for a CampusMindAI JWT token that authorizes all subsequent API operations.

Why API Authentication is Important

• Secure Access: Only authorized users can access CampusMindAI resources

• User Context: API operations are performed with appropriate user permissions

• Audit Trail: All actions are tracked and associated with specific users

Base URL

All API requests must be made relative to this base URL.

Development Environment

https://classbuddy-backend-dev.redbayf6dbaeae.northcentralus.azurecontainerapps.io

Authentication Flow

1. Obtain Azure AD Token - Use the Azure AD login script

2. Exchange for JWT Token - Call the /api/v1/login endpoint

3. Use JWT Token - Include in all API requests

Login Endpoint

Endpoint Details

• Method: GET

• URL: {{baseURL}}/api/v1/login

• Authentication: Azure AD Bearer token

Request

GET /api/v1/login HTTP/1.1
Host: <baseURL>
Authorization: Bearer <azure-ad-token>

Response

Status Code: 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

Error Responses

Using Bearer Tokens

All authenticated API requests must include the Authorization header with the JWT token:

Authorization: Bearer <jwt-access-token>

Example Request

curl -X POST "https://<baseURL>/api/v1/list_users/" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "limit": 10}'

Token Lifecycle

• JWT tokens are time-limited and expire after a set duration

• Expired tokens return 401 Unauthorized

• Re-authenticate using the Azure AD login script to obtain a fresh token

Common Authentication Errors

401 Unauthorized

Causes:

• Token not included in Authorization header

• Token format incorrect (missing "Bearer " prefix)

• Token has expired

• Token is from wrong environment

Solution: Re-authenticate and obtain a new JWT token

403 Forbidden

Causes:

• User role doesn't have access to the requested resource

• User is not a member of required groups

Solution: Contact administrator to update user role or group membership

404 Not Found

Causes:

• User authenticated with Azure AD but not registered in CampusMindAI

• User account was deleted

Solution: Administrator must invite user using the invite endpoint

Security Best Practices

1. Never hardcode tokens in application code

2. Use environment variables for storing tokens

3. Never commit tokens to version control

4. Implement token refresh logic for long-running applications

5. Clear tokens when no longer needed