AimableDocs
DocsAPI ReferenceRelease Notes

Connector Oauth

Updated 9 July 2026

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)
bash
curl -X GET \
  'https://api.aimable.com/api/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)

json
{
  "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)
bash
curl -X GET \
  'https://api.aimable.com/api/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)

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

Error Response (422)

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

Typical Workflow

  1. Initiate Authorization
    Frontend opens a popup to:

    code
    GET /api/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:

    code
    GET /api/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.

See Authentication & errors for request authentication and the standard error responses.

Related Endpoints

See also