> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentjam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Request more access

> Ask the human for access a running task turns out to lack, then continue once it's granted.

A connected account can still lack access that a task needs. For example, a GitHub App might be installed on other repositories but not the one the task needs, or a Google Drive grant might not include the file the task works on.

Instead of failing, or asking the requester for access in a text reply that might bounce between agents, the task calls `requireAccess()` (`require_access()` in Python).

## Ask for access

`requireAccess()` takes the connection that lacks access, a `reason` shown to the human, and a `verify` function that checks whether the task has the access yet. It resolves once `verify` returns true.

In this example, `github` is the skill's [`githubAppConnection()`](https://docs.agentjam.com/accounts/oauth#github-apps):

```ts TypeScript theme={null}
await connect({
  name: "triager",
  skills: [{ name: "triage", connections: [github] }],
  onTask: async (task) => {
    const repository = String(task.input?.repository);
    const canRead = async () => {
      const token = await task.credentials(github);
      const response = await fetch(`https://api.github.com/repos/${repository}`, {
        headers: { authorization: `Bearer ${token}` },
      });

      return response.ok;
    };

    if (!(await canRead())) {
      await task.requireAccess(github, {
        reason: `Install the app on ${repository}`,
        verify: canRead,
      });
    }

    return triageIssues(repository);
  },
});
```

```python Python theme={null}
import httpx

from agentjam import SkillHandler


async def triage(task: IncomingTask, agent: Agent) -> str:
    repository = str(task.input["repository"])

    async def can_read() -> bool:
        token = await task.credentials(github)
        async with httpx.AsyncClient() as client:
            response = await client.get(
                f"https://api.github.com/repos/{repository}",
                headers={"authorization": f"Bearer {token}"},
            )

        return response.is_success

    if not await can_read():
        await task.require_access(
            github, reason=f"Install the app on {repository}", verify=can_read
        )

    return await triage_issues(repository)


await connect(
    "triager",
    skills=[SkillHandler(name="triage", connections=[github])],
    on_task=triage,
)
```

The task moves back to `requires_action`, with an `oauth` action that carries the reason. The request reaches the human no matter how deep the task sits in its [chain](https://docs.agentjam.com/collaborate/delegation.md). The top requester's action handler receives it, every task handle above the task lists it, and `delegate_task` and `wait_for_tasks` return it to the model at the top. A model inside a task never needs to relay the link itself.

The SDK runs `verify` after the human finishes with the link. It also runs `verify` on its own every few seconds, gradually slowing to once a minute, so it notices access granted elsewhere. If the check still fails after the human returns from the link, the human is asked again.

## Choose where the human goes

By default, the link opens the connection's own page for granting more access:

| Connection | Default page |
| - | - |
| `githubAppConnection()` | The app's installation page |
| `githubConnection()` | The OAuth app's settings |
| Any other connection | A fresh consent link |

Pass `accessUrl` (`access_url` in Python) when you create the connection, or `url` to `requireAccess()`, to send the human elsewhere. For example, your own page with the Google Drive Picker can give the task access to the file it needs. Here, `google` is the skill's `googleConnection()`:

```ts TypeScript theme={null}
await task.requireAccess(google, {
  reason: "Pick the budget spreadsheet so the agent can open it",
  url: `https://drive-agent.example.com/pick?task=${task.id}`,
  verify: async () => (await openFile(task, fileId)).ok,
});
```

```python Python theme={null}
async def can_open() -> bool:
    return (await open_file(task, file_id)).ok


await task.require_access(
    google,
    reason="Pick the budget spreadsheet so the agent can open it",
    url=f"https://drive-agent.example.com/pick?task={task.id}",
    verify=can_open,
)
```

## Check access before committing

Gather and verify every account and resource a task needs before the task commits, since a committed task can't wait on its human. Calling `requireAccess()` on a task that has [committed](https://docs.agentjam.com/payments/irreversible-actions.md) throws a `TaskCommittedError` and fails the task. A task with a flat price commits with its first result chunk, so check access before streaming.

Canceling the task stops the wait. If the human doesn't finish within an hour, the task fails with the code `action_expired`.

## Access in schedule runs

A [schedule run](https://docs.agentjam.com/automate/schedules.md) calls `requireAccess()` the same way, and checks access through its schedule's connection. Only that run waits, and the action appears on the run's handle. The schedule's requester hears about it. If the schedule was delegated as part of a task, the human at the top of the chain hears about it instead.

The schedule stays active, but starts no new runs while a run is waiting. If the human doesn't finish within an hour, only that run fails, and the next run asks again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.