AimableDocs
DocsAPI Reference

Connector Oauth

OAuth Connectors

The connector-oauth domain enables secure integration of third-party services into the Aimable Platform using OAuth 2.0. It allows users to connect their external accounts (e.g., Google, GitHub, Salesforce) through a secure authorization flow, granting the platform limited access without exposing credentials.

This system is essential for enabling data synchronization, authentication delegation, and cross-platform functionality while maintaining user privacy and compliance with modern security standards.

Key Concepts

  • Provider Slug: A unique identifier for the third-party service (e.g., google, github, slack).
  • Collection ID & Space ID: UUIDs that bind the OAuth connection to specific resources within the Aimable Platform.
  • Authorization Flow: A browser-based OAuth flow initiated via popup. After user consent, the service redirects to a callback endpoint with a temporary code.
  • Callback Handling: The /callback endpoint exchanges the authorization code for tokens and completes the integration setup.

Endpoints

GET /v1/connectors/oauth/{provider_slug}/authorize

Starts the OAuth authorization flow. This endpoint should be opened in a browser popup.

Query Parameters:

  • collection_id (required): ID of the target collection.
  • space_id (required): ID of the target space.
  • redirect_uri (optional): Custom redirect URI.
  • connector_id (optional): Identifier for the connector instance.
  • token (optional): Pre-shared token for context.
  • tenant_id (optional): Identifier for multi-tenant environments.
Example Request (curl)
curl -X GET \
  'https://api.aimable.com/api-proxy/v1/connectors/oauth/google/authorize?collection_id=123e4567-e89b-12d3-a456-426614174000&space_id=123e4567-e89b-12d3-a456-426614174001&redirect_uri=https%3A%2F%2Fapp.aimable.com%2Foauth%2Fcallback&connector_id=conn_abc123&token=pre_shared_token&tenant_id=tenant_123' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

🔐 The Authorization: Bearer <token> header is required.

Success Response (200)
Returns an HTML page or redirect to the provider's OAuth consent screen. No JSON body is returned.

Error Response (422)

{
  "detail": [
    {
      "loc": ["query", "collection_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

GET /v1/connectors/oauth/{provider_slug}/callback

Handles the OAuth callback from the provider. The service sends a code and state parameter after user consent.

Example Request (curl)
curl -X GET \
  'https://api.aimable.com/api-proxy/v1/connectors/oauth/google/callback?code=auth_code_789&state=123e4567-e89b-12d3-a456-426614174000' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Parameters:

  • code (required): Authorization code from the provider.
  • state (required): Echoed from the initial request; used to verify context.

Success Response (200)

{
  "message": "OAuth connection established successfully",
  "provider": "google",
  "collection_id": "123e4567-e89b-12d3-a456-426614174000"
}

Error Response (422)

{
  "detail": [
    {
      "loc": ["query", "code"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Typical Workflow

  1. Initiate Authorization
    Frontend opens a popup to:

    GET /api-proxy/v1/connectors/oauth/google/authorize?
  collection_id=123e4567-e89b-12d3-a456-426614174000&
  space_id=123e4567-e89b-12d3-a456-426614174001&
  redirect_uri=https%3A%2F%2Fapp.aimable.com%2Foauth%2Fcallback

    Include Authorization: Bearer <user_token>.

  2. User Grants Consent
    The provider (e.g., Google) prompts the user. On approval, it redirects to the Aimable callback URL with code and state.

  3. Handle Callback
    The Aimable backend receives:

    GET /api-proxy/v1/connectors/oauth/google/callback?code=abc123&state=123e4567...

    Validates and stores the OAuth token for future use.

  4. Use Connected Account
    Subsequent API calls use the stored credentials to sync data or act on behalf of the user.

Authentication & Error Handling

  • All requests require a valid Authorization: Bearer <token> header.
  • Use short-lived, scoped tokens for enhanced security.
  • Handle 422 Unprocessable Entity errors by validating required parameters:
    • Ensure collection_id, space_id, and code/state are correctly passed.
    • Match the state parameter to prevent CSRF attacks.

This OAuth connector system ensures secure, user-approved integrations that power dynamic, data-rich experiences across the Aimable Platform.

Related Endpoints