> For the complete documentation index, see [llms.txt](https://docs.toolregistry.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolregistry.ai/concepts/act-as-user-userid.md).

# 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](#revocation "mention")).
  * 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.

<figure><img src="/files/E8FYu6yCvycecRZFu3mJ" alt=""><figcaption></figcaption></figure>