OAuth Authentication

OAuth 2.0 authentication with Google and GitHub

GET https://api.superbox.ai/v1/auth/oauth/{provider}

OAuth Authentication

cURL

curl --request GET \
  --url https://api.superbox.ai/v1/auth/oauth/{provider}

Supported Providers

Google OAuth

Sign in with Google account

GitHub OAuth

Sign in with GitHub account

OAuth Flow

1. Initiate OAuth

   Redirect user to provider authorization URL

   GET /auth/oauth/google
   GET /auth/oauth/github
   
2. User Authorization

   User grants permissions on provider site
3. Callback

   Provider redirects to callback URL with code https://superbox.ai/auth/callback?code=abc123&state=xyz

4. Token Exchange

   Backend exchanges code for user data and creates session

Google OAuth

Initiate Authorization

cURL
curl https://api.superbox.ai/v1/auth/oauth/google

Query Parameters

redirect_uri · string

Callback URL after authorization Default: https://superbox.ai/auth/callback

state · string

CSRF protection state parameter

GitHub OAuth

Initiate Authorization

GET /auth/oauth/github?redirect_uri=https://yourapp.com/callback

Requested Scopes

• user:email - Access user email
• read:user - Read user profile

Callback Handling

Success Response

{
  "user": {
    "id": "usr_1234567890",
    "email": "[e-mail]",
    "username": "areeb",
    "avatar_url": "https://avatars.githubusercontent.com/u/12345",
    "oauth_provider": "github",
    "oauth_id": "12345"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_abcdef123456..."
}

Error Responses

400 - Missing Code

{
  "error": "Missing authorization code",
  "message": "No code provided in callback"
}

Frontend Integration

React
function GoogleLogin() {
  const handleLogin = () => {
    const width = 500;
    const height = 600;
    const left = window.screen.width / 2 - width / 2;
    const top = window.screen.height / 2 - height / 2;
    
    const popup = window.open(
      'https://api.superbox.ai/v1/auth/oauth/google',
      'Google Login',
      `width=${width},height=${height},left=${left},top=${top}`
    );
    
    // Listen for callback
    window.addEventListener('message', (event) => {
      if (event.data.type === 'oauth_success') {
        const { token, user } = event.data;
        // Store token and update UI
      }
    });
  };
  
  return (
    <button onClick={handleLogin}>
      Sign in with Google
    </button>
  );
}