OOMOL Connector SaaS guide

Last updated on June 27, 2026

One complete integration has two parts: configure a project and service in OOMOL Console, then have your backend create authorization links for end users and execute Connector actions such as gmail.send_email.

Main topics:

• Which resources an administrator prepares in OOMOL Console.
• Which IDs and secrets your backend needs to store.
• What your frontend and backend do when an end user connects an account.
• How to select the connected account and execute an action.
• Which Console pages, statuses, logs, and usage views help with troubleshooting.

Integration model

A SaaS integration has a setup phase and a runtime phase.

The setup phase happens in OOMOL Console. It prepares the project, provider config, and backend API key, and records the IDs and secrets needed at runtime. End users are not part of these steps.

The runtime phase happens in your product backend. It represents your SaaS project when creating account links, reading connection request status, and executing actions. Runtime requests include the project API key:

authorization: Bearer <project-api-key>

The project API key stays on your backend. End users only use your product UI or open the OAuth authorization URL returned by Connector.

Data to store

A typical integration stores these values:

If your users can connect multiple Gmail accounts, store each account’s connectedAccountId or alias so runtime calls do not depend on the default “latest account” selection.

Step 1: Create a project

A project is the isolation boundary for a SaaS integration. It isolates provider configs, API keys, connected accounts, execution logs, and usage.

In OOMOL Console:

1. Open Projects from the left sidebar.
2. Click Create project.
3. Fill in the project name.
4. After creation, open the project and store the project ID as PROJECT_ID.

The project page has entries such as Provider configs, API Keys, Connected accounts, Execution logs, and Usage. The remaining setup happens inside this project.

The project name appears on the OAuth authorization entry page. Production integrations should use a product name end users can recognize, making the authorization target clear.

Step 2: Create a provider config

A provider config defines how this project connects to one Connector service. Runtime requests pass it as providerConfigId. For Gmail OAuth:

1. Open Provider configs from the project sidebar.
2. Click Create provider config.
3. Select or fill in these fields.
4. Click Create.

After creation, store the provider config ID as PROVIDER_CONFIG_ID. Your backend should pass it explicitly when creating authorization links and executing actions.

When each SaaS project uses its own OAuth client, change Client config source to a custom client and provide the matching clientId and clientSecret.

With a custom OAuth client, configure the Connector callback URL in the provider console. OOMOL Console or your deployment configuration provides that URL; end users do not need it.

For an API-key service, choose the matching API-key auth type. When an end user connects an account, your backend sends the user’s provider API key to Connector for storage.

Step 3: Create a project API key

The project API key is only for your backend. Do not send it to browsers, mobile clients, or end-user devices.

In the project page:

1. Open API Keys from the project sidebar.
2. Click Create API Key.
3. Fill in a key name. Use a name that makes rotation and troubleshooting easy, such as production server key or staging server key.
4. Click Create.
5. Copy the plaintext key from the one-time dialog and store it as PROJECT_API_KEY.

The plaintext key is returned only once. Later lists show only the key prefix, creation time, recent usage time, and similar metadata. If the key leaks, revoke it in Console and create a new one.

Step 4: Let the end user connect an account

Now move to the product runtime flow. Assume your product has a user with the ID customer-1, and they want to connect Gmail.

Your backend creates an OAuth authorization link:

CONNECTOR=https://connector.oomol.com
PROJECT_API_KEY=oo_proj_...

curl -sS -X POST "$CONNECTOR/v1/saas/connected-accounts/link" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $PROJECT_API_KEY" \
  -d '{
    "providerConfigId": "pc-1",
    "userId": "customer-1",
    "alias": "work",
    "returnUri": "https://app.example/connector/callback"
  }'

The response contains data.authorizationUrl, a Connector-owned authorization entry URL. Redirect the end user to this URL.

That page briefly shows the project display title, project icon, and provider config display name, then redirects to the real provider OAuth page. After the user authorizes, the provider calls back to Connector, and Connector redirects to the returnUri you provided.

On success, returnUri receives query parameters like:

status=success
service=gmail
providerConfigId=pc-1
externalUserId=customer-1
connectedAccountId=ca-1

Your frontend can send connectedAccountId to your backend for storage. The backend can also query the connection request status:

curl -sS "$CONNECTOR/v1/saas/connection-requests/$REQUEST_ID" \
  -H "authorization: Bearer $PROJECT_API_KEY"

If the user cancels or the provider returns an error, returnUri receives:

status=error
code=<connector-error-code>
message=<human-readable-message>

returnUri must use http or https. OAuth links expire after 10 minutes by default.

Step 5: Execute an action

After the account is connected, the backend can execute actions with the stored account selector.

curl -sS -X POST "$CONNECTOR/v1/saas/actions/gmail.send_email" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $PROJECT_API_KEY" \
  -H "x-request-id: req-saas-action-1" \
  -d '{
    "providerConfigId": "pc-1",
    "userId": "customer-1",
    "connectedAccountId": "ca-1",
    "input": {
      "to": "someone@example.com",
      "subject": "Hello",
      "body": "Hello from My SaaS"
    }
  }'

Rules:

• Pass exactly one of providerConfigId or service. Production integrations should prefer providerConfigId.
• Pass at most one of connectedAccountId or alias. Production integrations should pass one of them explicitly.
• If no account selector is present, Connector chooses the latest active connected account under the same projectId + providerConfigId + userId.
• The action ID service prefix must match the provider config service. For example, gmail.send_email must use a Gmail provider config.

The success response includes executionId, actionId, and the action output. Store executionId in your own operation logs for support and troubleshooting.

Step 6: Manage user connections

Products usually need to show users which accounts they have connected. The recommended approach is to store connectedAccountId, alias, service, providerConfigId, and your own userId in your product database after a successful callback, then render the account list from that data.

To verify Connector-side state, use Connected accounts in OOMOL Console to view connected accounts under the current project.

The available field tells whether the account can currently execute actions. It is true only when the provider config is active, the connected account is active, the underlying app is active, and a credential exists.

If your product lets users rename accounts, update the display name in your product database first. When an administrator needs to verify Connector-side state, use Console to inspect the matching account.

When a user disconnects an account, have your product backend run the disconnect flow and update your product database. Administrators can use Console to verify whether the account is still available.

Disconnect keeps the connected account record but removes the underlying credential. Historical logs can still reference the account; future actions cannot use it.

Step 7: Troubleshoot and operate

When troubleshooting a user’s action, open Execution logs in OOMOL Console. Common filters include providerConfigId, userId, appId, status=success|error, and action.

When troubleshooting, narrow the view by service or provider config first. If your operation logs store executionId, use it to connect one product-side operation with the Connector-side log.

For operations, use Usage to review daily usage trends and usage grouped by service. Common windows are 7, 30, or 90 days.

days supports only 7, 30, or 90.

What your backend calls at runtime

For the Gmail OAuth flow in this guide, the backend handles three jobs:

• Create an authorization link and send the user to the Connector authorization entry.
• Confirm the connection request after callback, then store connectedAccountId.
• Execute actions with the stored account when the user triggers a product feature.

Prefer OOMOL Console for setup and operations such as creating projects, creating provider configs, creating project API keys, reviewing connected accounts, reading execution logs, and checking usage.

Troubleshooting

When account connection or action execution fails, check in this order:

1. Confirm your backend is using the PROJECT_API_KEY for the current project, and that the key is not exposed to browsers or mobile clients.
2. Confirm the request uses the providerConfigId for the provider config you created.
3. Confirm the same user is not reusing an existing alias.
4. Open Connected accounts in Console and check whether the account is still available.
5. Open Execution logs in Console and filter by provider config, user ID, or executionId.