Documents

Technical Documentation for Authentication APIs

Authentication (auth) API Endpoints

This section describes all endpoints under the "auth" tag for the Alchemyst AI API v1. These endpoints are used to facilitate authentication for users via third-party providers (Atlassian, Google, Zoho), handle user session status, and perform logout actions. All endpoints are documented with technical accuracy and markdown formatting for clarity.

Table of Contents

Initiate Atlassian Authentication

Endpoint: `GET /api/auth/atlassian`

Description: Initiates the Atlassian OAuth authentication process, requesting access to the user's profile and email.

Responses:

  • `302` Redirects the user to the Atlassian OAuth consent screen for authentication.
    • `application/json`:
      • `{ "message": "Redirecting to Atlassian authentication" }`

Initiate Google Authentication

Endpoint: `GET /api/auth/google`

Description: Begins the Google OAuth authentication process, requesting profile and email permissions.

Responses:

  • `302` Redirects to Google OAuth consent screen.
    • `application/json`:
      • `{ "message": "Redirecting to Google authentication" }`

Handle Google OAuth Callback

Endpoint: `GET /api/auth/google/callback`

Description: Handles the OAuth callback from Google. Verifies authentication and, upon success, redirects the user to the dashboard.

Responses:

  • `302` Redirects to dashboard URL upon success.
  • `401` Authentication failed (invalid credentials or other error)
    • Example body: `{ "message": "Authentication failed" }`
  • `500` Internal error during authentication
    • Example body: `{ "message": "Internal server error" }`

Initiate Zoho Authentication

Endpoint: `GET /api/auth/zoho`

Description: Begins the Zoho OAuth authentication process, requesting access to user profile and email.

Responses:

  • `302` Redirects to Zoho OAuth consent screen for authentication.
    • `application/json`:
      • `{ "message": "Redirecting to Zoho authentication" }`

Logout and Clear Access Token

Endpoint: `GET /api/auth/logout`

Description: Clears the user's access token cookie, logging them out of the application.

Responses:

  • `200` Successfully logged out.
    • `application/json`:
      • `{ "success": true }`

Retrieve User Session Status

Endpoint: `GET /api/v1/auth/status`

Description: Retrieves the authenticated user's information based on the request headers.

Responses:

  • `200` User information retrieved.
    • `application/json`:
      • `{ "data": { "userId": "user123", "username": "john_doe" } }`
  • `404` User not found (no matching session/user).
    • `application/json`:
      • `{ "data": null }`

Example Authentication Flow

{

  "step1": "GET /api/auth/google → Redirects to Google OAuth consent screen",

  "step2": "User authenticates via Google",

  "step3": "GET /api/auth/google/callback → Validates authentication, redirects to dashboard on success"

}

Notes

  • All endpoints utilize standard HTTP status codes (e.g., 200, 302, 401, 404, 500) for error and success handling.
  • Third-party OAuth providers supported: Atlassian, Google, Zoho.
  • Session and logout endpoints allow status check and clearing of authentication on the client side as needed.

Response Code Reference

  • 302: Redirects for initiating authentication flows.
  • 200: Successful operation (e.g., logout, status fetch).
  • 401: Unauthorized (failed authentication or invalid credentials).
  • 404: Resource (user/session) not found.
  • 500: Internal server error (unexpected processing issue).

For more integration use cases or details, refer to the full API specification.