Authentication

Overview

suSHi uses OAuth 2.0 for authentication with support for Google and GitHub providers. After successful authentication, a JWT token is issued and stored as an HTTP-only cookie.

Get Authorization URL

curl "http://localhost:8080/api/v1/auth/url?to=google"

GET /api/v1/auth/url Retrieve the OAuth authorization URL for a specific provider.

Query Parameters

string

required

OAuth provider to use. Valid values:

google - Google OAuth
github - GitHub OAuth

Response

Returns the authorization URL as plain text:

https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&response_type=code&scope=...&state=...

Redirect the user to this URL to initiate the OAuth flow.

Error Responses

Show 400 - Missing Query Parameter

{
  "status": "Bad Request",
  "message": "Missing query param 'to'",
  "data": null
}

Show 400 - Invalid Provider

{
  "status": "Bad Request",
  "message": "Invalid query param 'to'",
  "data": null
}

OAuth Callback

GET /api/v1/auth/callback Handles the OAuth callback from the provider. This endpoint is called automatically by the OAuth provider after user authorization.

Query Parameters

state

string

required

OAuth state parameter (automatically provided by OAuth provider)

code

string

required

Authorization code (automatically provided by OAuth provider)

Response

On success:

User is created in the database (if they don’t exist)
JWT token is generated with 24-hour expiration
Token is set as HTTP cookie with the following properties:
- Name: jwt
- HttpOnly: false (⚠️ should be true in production for security)
- SameSite: Strict
- Secure: false (should be true in production with HTTPS)
- Path: /
- Expires: 24 hours from now
Redirects to /dashboard.html (HTTP 303)

JWT Token Claims

The JWT token contains the following claims:

{
  "username": "[email protected]",
  "iat": 1709481600,
  "exp": 1709568000
}

username

string

User’s email address from OAuth provider

iat

number

Issued at timestamp (Unix epoch)

exp

number

Expiration timestamp (Unix epoch, 24 hours after issuance)

Error Responses

Show 400 - Missing State

{
  "status": "Bad Request",
  "message": "Missing query param 'state'",
  "data": null
}

Show 400 - Missing Code

{
  "status": "Bad Request",
  "message": "Missing query param 'code'",
  "data": null
}

Show 400 - Invalid State

{
  "status": "Bad Request",
  "message": "Invalid query param 'state'",
  "data": null
}

Show 500 - OAuth Error

{
  "status": "Internal Server Error",
  "message": "Error message from OAuth provider",
  "data": null
}

Logout

cURL

curl -X GET "http://localhost:8080/api/v1/auth/logout" \
  -b "jwt=your-jwt-token"

GET /api/v1/auth/logout Invalidates the current JWT token by expiring the cookie.

Response

{
  "status": "OK",
  "message": "Logged out successfully",
  "data": null
}

The JWT cookie is expired by setting its expiration time to 10 seconds in the past.

JWT Authentication for API Requests

All endpoints under /api/v1/* (except /api/v1/auth/*) require JWT authentication.

Implementation Details

Algorithm: HS256 (HMAC-SHA256)
Token Location: HTTP cookie named jwt
Token Lifetime: 24 hours
Middleware: Uses jwtauth verifier and authenticator

Using JWT in Requests

The JWT token is automatically included in requests when using a browser. For API clients:

curl -X GET "http://localhost:8080/api/v1/machines" \
  -b "jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Extracting Username from Token

All protected endpoints extract the username from the JWT token claims:

username := claims["username"].(string)

This username is used for authorization and data filtering.

Error Responses

Show 401 - Missing Token

{
  "status": "Unauthorized",
  "message": "No token found",
  "data": null
}

Show 401 - Invalid Token

{
  "status": "Unauthorized",
  "message": "Invalid token",
  "data": null
}

Show 401 - Expired Token

{
  "status": "Unauthorized",
  "message": "Token is expired",
  "data": null
}

Endpoints

Authentication

Overview

Get Authorization URL

Query Parameters

Response

Error Responses

OAuth Callback

Query Parameters

Response

JWT Token Claims

Error Responses

Logout

Response

JWT Authentication for API Requests

Implementation Details

Using JWT in Requests

Extracting Username from Token

Error Responses

Build docs developers (and LLMs) love

Endpoints

​Overview

​Get Authorization URL

​Query Parameters

​Response

​Error Responses

​OAuth Callback

​Query Parameters

​Response

​JWT Token Claims

​Error Responses

​Logout

​Response

​JWT Authentication for API Requests

​Implementation Details

​Using JWT in Requests

​Extracting Username from Token

​Error Responses

Build docs developers (and LLMs) love

Overview

Get Authorization URL

Query Parameters

Response

Error Responses

OAuth Callback

Query Parameters

Response

JWT Token Claims

Error Responses

Logout

Response

JWT Authentication for API Requests

Implementation Details

Using JWT in Requests

Extracting Username from Token

Error Responses