AimableDocs
DocsAPI ReferenceRelease Notes

Connector Providers

Updated 9 July 2026

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.

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

Response (200 OK):

json
{
  "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.

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

bash
curl -X POST "https://api.aimable.com/api/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):

json
{
  "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.

bash
curl -X DELETE "https://api.aimable.com/api/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.

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

Related Endpoints

See also