Skip to main content

​
Overview

PentAGI uses session-based authentication with support for multiple authentication providers. All API requests require valid authentication.

​
Authentication Methods

​
Local Authentication

Authenticate with username and password: 
curl -X POST https://your-server/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-username",
    "password": "your-password"
  }'

​
OAuth Providers

PentAGI supports OAuth authentication via:

Google OAuth

Authenticate using Google accounts

GitHub OAuth

Authenticate using GitHub accounts

​
OAuth Flow

  1. Initiate OAuth
GET /api/v1/auth/authorize?provider=google
  1. Handle Callback
After OAuth provider redirects: 
GET /api/v1/auth/login-callback?code=...&state=...
  1. Session Cookie
Successful authentication sets an HTTP-only session cookie named auth.

​
Session Management

​
Session Duration

Sessions are valid for 4 hours by default. The session timeout can be configured during server setup.

​
Check Authentication Status

Verify your current session: 
curl https://your-server/api/v1/info \
  -H "Cookie: auth=your-session-cookie"
Response: 
{
  "authenticated": true,
  "user": {
    "id": "123",
    "username": "your-username",
    "role": "admin"
  },
  "providers": {
    "google": true,
    "github": false
  }
}

​
Logout

End your session: 
GET /api/v1/auth/logout

​
Using Sessions with GraphQL

Include the session cookie in all GraphQL requests: 
curl -X POST https://your-server/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Cookie: auth=your-session-cookie" \
  -d '{
    "query": "query { flows { id title status } }"
  }'

​
WebSocket Authentication

For GraphQL subscriptions over WebSocket:
  1. Establish WebSocket connection with session cookie
  2. Send connection init message
  3. User ID is extracted from the session
const ws = new WebSocket('ws://your-server/api/v1/graphql', {
  headers: {
    Cookie: 'auth=your-session-cookie'
  }
});

ws.send(JSON.stringify({
  type: 'connection_init',
  payload: {}
}));

​
Permissions

PentAGI implements role-based access control (RBAC). Each user role has specific permissions:

​
Permission Scopes

View flows owned by the authenticated user
View and manage all flows (admin only)
Access LLM provider configurations
View Docker containers for user’s flows
Access terminal logs for user’s flows

​
Error Responses

​
401 Unauthorized

{
  "errors": [{
    "message": "unauthorized",
    "extensions": {
      "code": "UNAUTHENTICATED"
    }
  }]
}

​
403 Forbidden

{
  "error": "not_permitted",
  "message": "User does not have required permissions"
}

​
Security Best Practices

Always use HTTPS in production to protect session cookies and credentials.
Session cookies are HTTP-only and cannot be accessed via JavaScript, providing protection against XSS attacks.

​
CORS Configuration

Configure allowed origins via the CORS_ORIGINS environment variable: 
CORS_ORIGINS=https://your-frontend.com,https://another-domain.com
Session cookies are signed using the COOKIE_SIGNING_SALT environment variable. Keep this secret secure.

Build docs developers (and LLMs) love

Get started for freeTalk to us