Documents

Generate API Documentation

Authentication Guide for the Context API

This documentation explains how to authenticate and interact with the Alchemyst AI Context API, based strictly on the provided OpenAPI 3.0 specification.

Overview

All endpoints for context management in Alchemyst AI require authentication. Access to the API is secured using a Bearer Token (JWT) which must be included in the Authorization header of your HTTP requests.

Authentication Flow

1. Initiate OAuth Authentication

You must sign in via one of the supported OAuth providers to obtain a session:

  • Atlassian: GET /api/auth/atlassian (redirects to Atlassian consent)
  • Google: GET /api/auth/google (redirects to Google consent)
  • Zoho: GET /api/auth/zoho (redirects to Zoho consent)

These endpoints initiate the OAuth sign-in process. After successful authentication, you will be redirected to your dashboard with an access token stored (often in a secure HTTP-only cookie or returned as a bearer token).

Example: ``` GET /api/auth/google ``` Response: Redirects you to Google OAuth consent. On success, redirects back with credentials.

2. Retrieve Authenticated User Status

Use the following endpoints to verify your authentication status or retrieve user info:

  • GET /api/v1/auth/status
  • GET /api/v1/status

Example: ``` GET /api/v1/auth/status Authorization: Bearer ``` Response: 200 OK with user info, or 401/404 if not authenticated.

3. Using the Bearer Token

All context API endpoints require the Bearer token for authorization. You must include the following HTTP header in your requests:

``` Authorization: Bearer ```

If the token is missing or invalid, endpoints will return 401 Unauthorized.

Authentication Errors

  • 401 Unauthorized: Sent if the user is not authenticated or token is invalid.
  • 403 Forbidden: User lacks required permissions/scope.

Example: Add Context Data

```json POST /api/v1/context/add Headers: Authorization: Bearer Content-Type: application/json

Body: { "user_id": "user123", "organization_id": "org456", "documents": [ { "content": "Some document text" } ], "source": "myapp", "context_type": "resource", "scope": "internal", "metadata": { "fileName": "file.pdf", "fileType": "application/pdf", "fileSize": 10240, "lastModified": 1680000000000 } } ```

Logging Out

To terminate your session and clear the stored access token, use:

  • GET /api/auth/logout

Example: ``` GET /api/auth/logout ``` Response: 200 OK, clears the access token and logs out.

Summary Table: Authentication Endpoints

Endpoint Method Purpose
/api/auth/atlassian GET Initiate Atlassian OAuth
/api/auth/google GET Initiate Google OAuth
/api/auth/zoho GET Initiate Zoho OAuth
/api/v1/auth/status GET Retrieve current user info
/api/v1/status GET Retrieve authenticated user status
/api/auth/logout GET Logout and clear token

Notes

  • All context management endpoints (add, delete, search, view) require a valid Bearer token.
  • OAuth token is typically managed as a cookie or must be handled in the client as a JWT for Authorization.
  • Always use HTTPS to ensure token security.

For full details on available context endpoints and their usage, refer to the Context API section.