OpenConnector credentials, runtime tokens & OAuth

Runtime access and provider credentials

Admin credentials protect the console and /api endpoints. Runtime tokens authorize /v1 and /mcp clients. Provider credentials belong to the connected app account and stay inside the runtime; these credentials are not interchangeable.

Register your OAuth app

For self-hosting, register an OAuth app with the provider and copy the exact expectedRedirectUri from /api/oauth/configs. Set OOMOL_CONNECT_ORIGIN to the public origin before configuring a remote callback. Authorize only the scopes your workflow needs.

Choose the account connection

A call without an alias uses the default provider connection. Select a named connection with x-oo-connector-alias. Runtime-token connection grants may restrict which accounts a client can use.

Persist and protect credentials

The Docker image uses /app/data for local runtime data. Keep it on a persistent volume. Configure OOMOL_CONNECT_ENCRYPTION_KEY for stored credentials and keep the key available for recovery; consult the deployment guide before exposing the runtime.

Complete the OAuth connection

1. First set OOMOL_CONNECT_ORIGIN to the address your browser uses. Read /api/oauth/configs and copy the provider’s expectedRedirectUri exactly into your OAuth app. Add your admin bearer token when admin authentication is enabled.
2. In the local console, save the provider’s OAuth client ID and secret. Choose a subset of the provider’s declared scopes if needed, start authorization, and approve access in the provider’s browser flow.
3. After the callback, inspect /api/connections. Confirm the account identity and connection name before calling an Action. A named connection must already exist; selecting an alias does not create one.

The first request below inspects configured accounts using the admin token. The second calls a read-only Action with the runtime token and an existing work connection. Replace the connection name with your own; omit the alias header for the default connection.

curl -s http://localhost:3000/api/connections \
  -H "Authorization: Bearer $OOMOL_CONNECT_ADMIN_TOKEN"

curl -s -X POST \
  http://localhost:3000/v1/actions/github.get_current_user \
  -H "Authorization: Bearer $OOMOL_CONNECT_RUNTIME_TOKEN" \
  -H 'x-oo-connector-alias: work' \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

Read the result

HTTP runtime responses use success, message, data and meta. Inspect success and the Action’s output schema, not just the HTTP status. When execution metadata includes executionId, use it to find the corresponding redacted run log. The example below illustrates the envelope; it is not a live API result.

{
  "success": true,
  "message": "OK",
  "data": {},
  "meta": {}
}

If the call fails

• For an authentication failure, check the endpoint and credential type: admin access protects /api; a runtime bearer token authorizes /v1 and /mcp. A provider API key is not a runtime token.
• For a permission denial, check the Action’s required scopes, runtime Action rules and connection grants. A valid token may still be forbidden from using the selected account.
• For empty or missing results, confirm the connected account and its access to the requested resource. Successful authorization does not grant access to every workspace, channel or document.
• Inspect the error and run log before retrying. If an Action changes provider data, check whether it already completed; do not blindly repeat the request.