# 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toolregistry.ai/concepts/act-as-user-userid.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.