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():
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. 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:
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():
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. CallingrequireAccess() on a task that has committed 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 callsrequireAccess() 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.