AimableDocs
DocsAPI Reference

Connector Providers

Connector Providers

The connector-providers domain in the Aimable Platform API (v0.1.0) allows administrators to manage third-party service integrations—known as connector providers—that enable data synchronization and authentication with external platforms (e.g., Google Workspace, Salesforce, or Slack). These providers define how authentication is handled, what scopes are required, and how connections are executed.

Managing connector providers is essential for setting up and maintaining secure, functional integrations. Each provider must be configured with credentials (like client_id and client_secret) before users can connect their accounts.

Key Concepts

  • Provider Slug: A unique string identifier for each connector provider (e.g., google-workspace, github).
  • Auth Type: The authentication method used (e.g., oauth2).
  • Config Schema: JSON schema defining required configuration fields for setup.
  • Setup Complete: Boolean indicating whether the provider has been successfully configured at the system level.
  • Default Scopes: Predefined OAuth scopes used during integration.

Administrative access is required to manage these resources.

How to Use the Endpoints

1. List All Connector Providers

Retrieve all available connector providers.

curl -X GET "https://api.aimable.com/api-proxy/v1/admin/connector-providers" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-API-Key: your-api-key"

Response (200 OK):

{
  "data": [
    {
      "id": "a1b2c3d4-1234-5678-90ab-cdef12345678",
      "provider_slug": "google-workspace",
      "display_name": "Google Workspace",
      "auth_type": "oauth2",
      "execution_strategy": "server-side",
      "default_scopes": [
        { "name": "https://www.googleapis.com/auth/gmail.readonly", "description": "Read Gmail messages" },
        { "name": "https://www.googleapis.com/auth/calendar", "description": "Read calendar events" }
      ],
      "config_schema": {
        "client_id": { "type": "string", "format": "uuid" },
        "client_secret": { "type": "string" }
      },
      "setup_complete": true,
      "created_at": "2023-10-01T12:00:00Z",
      "updated_at": "2023-10-05T14:30:00Z"
    }
  ]
}

2. Get a Specific Connector Provider

Fetch details for a single provider by its slug.

curl -X GET "https://api.aimable.com/api-proxy/v1/admin/connector-providers/google-workspace" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-API-Key: your-api-key"

Returns the same structure as above, but for a single provider.

3. Set Up a Connector Provider

Configure a provider with credentials.

curl -X POST "https://api.aimable.com/api-proxy/v1/admin/connector-providers/google-workspace/setup" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "client_id": "1234567890-abcxyz.apps.googleusercontent.com",
    "client_secret": "your-client-secret-value"
  }'

Response (200 OK):

{
  "data": {
    "id": "a1b2c3d4-1234-5678-90ab-cdef12345678",
    "provider_slug": "google-workspace",
    "display_name": "Google Workspace",
    "auth_type": "oauth2",
    "execution_strategy": "server-side",
    "default_scopes": [
      { "name": "https://www.googleapis.com/auth/gmail.readonly", "description": "Read Gmail messages" }
    ],
    "config_schema": { ... },
    "setup_complete": true,
    "created_at": "2023-10-01T12:00:00Z",
    "updated_at": "2023-10-06T09:15:00Z"
  }
}

4. Reset a Connector Provider

Remove stored credentials and reset setup status.

curl -X DELETE "https://api.aimable.com/api-proxy/v1/admin/connector-providers/google-workspace/setup" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-API-Key: your-api-key"

Returns the updated provider object with "setup_complete": false.

Common Workflow: Setting Up a New Provider

  1. List Providers
    Use GET /v1/admin/connector-providers to find the provider_slug you want to configure.

  2. Inspect Configuration Requirements
    Use GET /v1/admin/connector-providers/{provider_slug} to view the config_schema and determine required fields.

  3. Perform Setup
    Send a POST request to /setup with valid client_id and client_secret.

  4. Verify Setup
    Re-fetch the provider to confirm "setup_complete": true.

  5. Reset if Needed
    If credentials are compromised or invalid, use DELETE /setup to reset and reconfigure.

Authentication & Error Handling

  • All endpoints require authentication via Authorization: Bearer <token>.
  • Optional X-API-Key header may be used for additional identification.
  • Common errors:
    • 401 Unauthorized: Missing or invalid access token.
    • 403 Forbidden: User lacks admin privileges.
    • 422 Unprocessable Entity: Invalid input (e.g., malformed provider_slug).

Example error:

{
  "detail": [
    {
      "loc": ["path", "provider_slug"],
      "msg": "Invalid provider slug",
      "type": "value_error",
      "input": "invalid-slug!"
    }
  ]
}

Use these patterns to automate integration setup and ensure robust, maintainable connections.

Related Endpoints