Endpoints

The Authentication service provides several endpoints for token management, validation, and service monitoring.

Service Information

GET /

Returns service health status and information.

Response

{
  "status": "healthy",
  "env": "production",
  "ui": "https://auth.genstack.app/ui"
}

Status Codes

• 200 - Service is healthy
• 503 - Service is unhealthy

Token Management

POST /token

Generates a new Genstack authentication token for a user.

Request

Content-Type: application/json

{
  "userId": "user_123",
  "clerkToken": "clerk_token_xyz",
  "lifetimeSeconds": 3600
}

Response

{
  "genstackToken": "genstack_token_xyz"
}

Token Validation

POST /validate

Validates a Genstack token and returns token information.

Request

Content-Type: application/json

{
  "genstackToken": "token_to_validate"
}

Response

{
  "valid": true,
  "userId": "user_123",
  "isMarketing": false,
  "expiresAt": "2024-01-22T12:00:00Z"
}

Session Management

POST /logout

Logs out a user by revoking their Genstack token and optionally their Clerk sessions.

Request

Content-Type: application/json

{
  "genstackToken": "token_to_revoke",
  "clerkToken": "clerk_token_to_revoke" // Optional
}

Response

{
  "status": "success",
  "message": "Logged out successfully and revoked all Clerk sessions"
}

Web Interface

GET /ui

Provides a web-based interface for authentication.

Query Parameters

Response

Returns an HTML page with the authentication interface.

Error Responses

All error responses follow this format:

{
  "error": {
    "type": "ErrorType",
    "message": "Description of what went wrong",
    "details": {
      // Additional error context
    }
  }
}

Common error types include:

• InvalidRequest
• InvalidCredentials
• SessionExpired
• InternalError