Act‑as‑User (userId)

Purpose userId binds a run to a specific identity. That identity’s OAuth/API keys are used for all tool calls for the given integration. This determines which user’s permissions and data will be used when executing the run. Choose the user whose perspective should be used for the operation.

Behavior

  • Reuse: If you (or your AI Agent) provide a previously used userId, the stored OAuth tokens for that user are reused, and your agent can act on behalf of that user.

  • Least privilege: Pick the user with the minimum required permissions.

  • Security: Treat userId as sensitive. Don’t expose it unnecessarily in logs or UI.

  • Revocation: Tokens are revoked at the integration level; once re-authorized, the same userId can be reused.

  • Audit trail: Reusing the same userId across runs preserves a consistent audit trail.

OAuth Flow

  • If a new identity is provided, or the user does not yet have the required OAuth scopes to fulfill the plan, an OAuth flow is triggered automatically to collect the missing scopes.

  • During this process, the system will return OAuth authentication links in the Server-Sent Events (SSE) stream. Your client (or AI Agent) is responsible for handling these links and surfacing them to the user to complete authorization.

  • Once the flow is completed, the tokens are stored and reused for subsequent runs tied to the same userId.

OAuth Token Lifetime & Refresh

TL;DR: “OAuth tokens are kept alive by toolregistry.ai until revoked. We keep tokens refreshed until the integration allows.”

What happens Toolregistry.ai keeps OAuth tokens alive and refreshed for the selected userId until you revoke them or the integration stops honoring refresh.

How it works

  • Auto-refresh: We rotate access tokens using the provider’s refresh token before expiry.

  • Until it can’t: Refresh continues until one of the following:

    • You revoke access (see Revocation).

    • The provider invalidates/rotates the refresh token (invalid_grant, etc.).

    • Required scopes change and re-consent is needed.

    • Tenant/policy disables offline access or long-lived refresh.

    • Consent is withdrawn or the account is disabled.

Revocation

Tokens are revoked at the integration level. Once re-authorized, the same userId can be reused.

To revoke:

  1. Navigate to Integrations > Integration Users.

  2. Enter the exact userId you want to revoke to search box - it will reveal the user.

  3. Confirm the action — access for that identity will be removed until re-authorization.

PreviousIntegration Selection

Last updated