API Routes - OAuth Service Connections

This document describes OAuth connection endpoints for integrating external services (Gmail, Drive, Facebook, GitHub, Spotify).

Base URL

http://localhost:8080

General Endpoints

GET /api/connections

Description: List all services and their connection status for the current user.

Authentication: Required (Bearer token)

Request Headers:

Authorization: Bearer <token>

Success Response (200 OK):

{
  "connections": [
    {
      "service_id": 2,
      "service_name": "gmail",
      "display_name": "Gmail",
      "description": "Email automation service",
      "is_connected": true,
      "connected_at": "2025-12-15T10:00:00Z"
    },
    {
      "service_id": 3,
      "service_name": "facebook",
      "display_name": "Facebook",
      "description": "Social media automation",
      "is_connected": false,
      "connected_at": null
    }
  ]
}

Response Fields:

Error Responses:

Example:

curl -X GET http://localhost:8080/api/connections \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

DELETE /api/connections/reset

Description: Disconnect all OAuth services for the current user. This removes all stored access tokens and service connections.

Authentication: Required (Bearer token)

Request Headers:

Authorization: Bearer <token>

Request Body: None required

Success Response (200 OK):

{
  "message": "Successfully disconnected 4 service(s)",
  "disconnected_count": 4
}

Response Fields:

Error Responses:

Example:

curl -X DELETE http://localhost:8080/api/connections/reset \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Gmail OAuth Connections

GET/POST /api/connections/gmail

Description: Initiate the Gmail OAuth2 authentication flow. Redirects the user to Google’s consent screen to authorize Gmail access.

Authentication: Required (Bearer token or URL parameter)

Request Headers:

Authorization: Bearer <token>

OR Query Parameters:

Success Response (302 Redirect): Redirects user to Google OAuth consent screen where they can authorize Gmail access.

OAuth Scopes Requested:

• openid - Basic OpenID authentication
• email - User’s email address
• profile - User’s basic profile information
• https://www.googleapis.com/auth/gmail.readonly - Read-only access to Gmail
• https://www.googleapis.com/auth/drive - Access to Google Drive

Error Responses:

Example:

# Using Authorization header
curl -X GET http://localhost:8080/api/connections/gmail \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Using URL parameter (useful for browser redirects)
# In browser, navigate to:
http://localhost:8080/api/connections/gmail?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

GET /api/connections/gmail/callback

Description: Handles the OAuth2 callback from Google after user authorization. This endpoint is called automatically by Google and should not be called directly.

Authentication: Not required (callback from Google, uses session data)

Query Parameters:

Success Response (200 OK):

{
  "success": true,
  "message": "Gmail and Drive connected successfully",
  "connections": {
    "gmail": {
      "id": 1,
      "user_id": 1,
      "service_id": 2,
      "service_name": "gmail",
      "service_display_name": "Gmail",
      "connected_at": "2025-12-15T10:00:00Z",
      "updated_at": "2025-12-15T10:00:00Z",
      "token_expires_at": "2025-12-15T11:00:00Z"
    },
    "drive": {
      "id": 2,
      "user_id": 1,
      "service_id": 3,
      "service_name": "drive",
      "service_display_name": "Google Drive",
      "connected_at": "2025-12-15T10:00:00Z",
      "updated_at": "2025-12-15T10:00:00Z",
      "token_expires_at": "2025-12-15T11:00:00Z"
    }
  }
}

Response Fields:

Error Responses:

Example:

# This endpoint is called automatically by Google after user consent
# You cannot call it directly - it requires valid OAuth state and code from Google

DELETE /api/connections/gmail

Description: Disconnect Gmail service by removing the stored OAuth connection. This revokes the application’s access to the user’s Gmail account.

Authentication: Required (Bearer token)

Request Headers:

Authorization: Bearer <token>

Request Body: None required

Success Response (200 OK):

{
  "message": "Gmail disconnected successfully"
}

Error Responses:

Example:

curl -X DELETE http://localhost:8080/api/connections/gmail \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Facebook OAuth Connections

GET/POST /api/connections/facebook

Description: Initiate the Facebook OAuth2 authentication flow. Redirects the user to Facebook’s consent screen to authorize Facebook access.

Authentication: Required (Bearer token or URL parameter)

Request Headers:

Authorization: Bearer <token>

OR Query Parameters:

Success Response (302 Redirect): Redirects user to Facebook OAuth consent screen where they can authorize Facebook access.

OAuth Scopes Requested:

• email - User’s email address
• public_profile - User’s basic profile information (name, picture)
• user_posts - Access to user’s posts

Error Responses:

Example:

# Using Authorization header
curl -X GET http://localhost:8080/api/connections/facebook \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Using URL parameter (useful for browser redirects)
# In browser, navigate to:
http://localhost:8080/api/connections/facebook?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

GET /api/connections/facebook/callback

Description: Handles the OAuth2 callback from Facebook after user authorization. This endpoint is called automatically by Facebook and should not be called directly.

Authentication: Not required (callback from Facebook, uses session data)

Query Parameters:

Success Response (200 OK):

{
  "success": true,
  "message": "Facebook connected successfully",
  "connection": {
    "id": 1,
    "user_id": 1,
    "service_id": 4,
    "service_name": "facebook",
    "service_display_name": "Facebook",
    "connected_at": "2025-12-15T10:00:00Z",
    "updated_at": "2025-12-15T10:00:00Z",
    "token_expires_at": "2026-02-12T10:00:00Z"
  }
}

Response Fields:

Error Responses:

Example:

# This endpoint is called automatically by Facebook after user consent
# You cannot call it directly - it requires valid OAuth state and code from Facebook

DELETE /api/connections/facebook

Description: Disconnect Facebook service by removing the stored OAuth connection. This revokes the application’s access to the user’s Facebook account.

Authentication: Required (Bearer token)

Request Headers:

Authorization: Bearer <token>

Request Body: None required

Success Response (200 OK):

{
  "message": "Facebook disconnected successfully"
}

Error Responses:

Example:

curl -X DELETE http://localhost:8080/api/connections/facebook \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

GitHub OAuth Connections

GET/POST /api/connections/github

Description: Initiate the GitHub OAuth2 authentication flow. Redirects the user to GitHub’s consent screen to authorize GitHub access.

Authentication: Required (Bearer token or URL parameter)

Request Headers:

Authorization: Bearer <token>

OR Query Parameters:

Success Response (302 Redirect): Redirects user to GitHub OAuth consent screen where they can authorize GitHub access.

OAuth Scopes Requested:

• repo - Full control of private and public repositories
• read:user - Read user profile data
• user:email - Access to user’s email addresses

Error Responses:

Example:

# Using Authorization header
curl -X GET http://localhost:8080/api/connections/github \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Using URL parameter (useful for browser redirects)
# In browser, navigate to:
http://localhost:8080/api/connections/github?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

GET /api/connections/github/callback

Description: Handles the OAuth2 callback from GitHub after user authorization. This endpoint is called automatically by GitHub and should not be called directly.

Authentication: Not required (callback from GitHub, uses session data)

Query Parameters:

Success Response (200 OK):

{
  "success": true,
  "message": "GitHub connected successfully",
  "connection": {
    "id": 1,
    "user_id": 1,
    "service_id": 5,
    "service_name": "github",
    "service_display_name": "GitHub",
    "connected_at": "2025-12-15T10:00:00Z",
    "updated_at": "2025-12-15T10:00:00Z",
    "token_expires_at": "2026-12-15T10:00:00Z"
  }
}

Response Fields:

Error Responses:

Example:

# This endpoint is called automatically by GitHub after user consent
# You cannot call it directly - it requires valid OAuth state and code from GitHub

DELETE /api/connections/github

Description: Disconnect GitHub service by removing the stored OAuth connection. This revokes the application’s access to the user’s GitHub account.

Authentication: Required (Bearer token)

Request Headers:

Authorization: Bearer <token>

Request Body: None required

Success Response (200 OK):

{
  "message": "GitHub disconnected successfully"
}

Error Responses:

Example:

curl -X DELETE http://localhost:8080/api/connections/github \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Spotify OAuth Connections

GET/POST /api/connections/spotify

Description: Initiate the Spotify OAuth2 authentication flow. Redirects the user to Spotify’s consent screen to authorize Spotify access.

Authentication: Required (Bearer token or URL parameter)

Request Headers:

Authorization: Bearer <token>

OR Query Parameters:

Success Response (302 Redirect): Redirects user to Spotify OAuth consent screen where they can authorize Spotify access.

OAuth Scopes Requested:

• user-read-playback-state - Read playback state
• user-modify-playback-state - Control playback
• playlist-read-private - Read private playlists
• playlist-modify-public - Modify public playlists
• playlist-modify-private - Modify private playlists
• user-library-read - Read saved tracks
• user-library-modify - Modify saved tracks

Error Responses:

Example:

# Using Authorization header
curl -X GET http://localhost:8080/api/connections/spotify \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Using URL parameter (useful for browser redirects)
# In browser, navigate to:
http://localhost:8080/api/connections/spotify?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

GET /api/connections/spotify/callback

Description: Handles the OAuth2 callback from Spotify after user authorization. This endpoint is called automatically by Spotify and should not be called directly.

Authentication: Not required (callback from Spotify, uses custom state storage)

Query Parameters:

Success Response (200 OK):

{
  "success": true,
  "message": "Spotify connected successfully",
  "connection": {
    "id": 1,
    "user_id": 1,
    "service_id": 6,
    "service_name": "spotify",
    "service_display_name": "Spotify",
    "connected_at": "2025-12-15T10:00:00Z",
    "updated_at": "2025-12-15T10:00:00Z",
    "token_expires_at": "2025-12-15T11:00:00Z"
  }
}

Response Fields:

Error Responses:

Example:

# This endpoint is called automatically by Spotify after user consent
# You cannot call it directly - it requires valid OAuth state and code from Spotify

DELETE /api/connections/spotify

Description: Disconnect Spotify service by removing the stored OAuth connection. This revokes the application’s access to the user’s Spotify account.

Authentication: Required (Bearer token)

Request Headers:

Authorization: Bearer <token>

Request Body: None required

Success Response (200 OK):

{
  "message": "Spotify disconnected successfully"
}

Error Responses:

Example:

curl -X DELETE http://localhost:8080/api/connections/spotify \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Related Documentation

• Authentication Endpoints
• Services & Workflows
• OAuth2 Implementation