Skip to content

revoke_consent.py

Remove specific scopes from, or entirely delete, the delegated consent grant that lets the Agent Identity act as the Agent User. The inverse of grant_consent.py.

Part of the auth-and-certs command reference.

Purpose

Pares down or deletes the Agent Identity → Agent User oauth2PermissionGrant. Use it to remove delegated scopes the agent no longer needs, or to fully revoke the grant. It operates only on the delegated consent record (oauth2PermissionGrants); it does not touch application permissions (appRoleAssignments) or any other resource.

See Token flows → Consent records for how the grant is consumed at Hop 3.

Requirements

  • .entrabot-state.json must contain AGENT_OBJECT_ID (Agent Identity service-principal object ID) and AGENT_USER_ID (Agent User object ID).
  • The Provisioner app must already exist with its certificate available for cert-auth — the private key lives in the OS keystore on macOS/Linux, or in an ACL-locked file under %LOCALAPPDATA%\entrabot\ on Windows; this command uses the existing-only token helper and never bootstraps it.
  • The Provisioner needs DelegatedPermissionGrant.ReadWrite.All.

Usage

# Remove specific scopes (comma- or space-separated)
python3 scripts/revoke_consent.py --scopes "Mail.Read,Files.ReadWrite"

# Delete the entire grant
python3 scripts/revoke_consent.py --all

Options

  • --scopes SCOPES — comma- or space-separated scope names to remove.
  • --all — remove every current scope, which deletes the grant.
  • --help, -h — print usage and exit.

Both --scopes and --all are accepted on the command line; at least one is required. If both are supplied, --all takes precedence — the command targets every current scope in the grant, ignoring the --scopes list.

Effects

  1. Reads the Agent Identity and Agent User object IDs from state and mints a Provisioner Graph token (certificate key read from the OS keystore, or from the Windows file-backed store, in memory only).
  2. Finds the matching grant by clientId and principalId (first match).
  3. Computes the change:
  4. With --all, targets every current scope, overriding any --scopes value that was also supplied.
  5. With --scopes alone, intersects the request with the grant's current scopes. Scopes not present in the grant are ignored.
  6. Applies the smallest change:
  7. No requested scope is actually present → prints a no-op message, makes no change.
  8. Scopes remain after removal → PATCH the grant to the reduced scope set.
  9. No scopes remain (or --all) → DELETE the grant entirely.

Exit behavior

  • 0 — scopes removed, grant deleted, or nothing to remove (no matching scopes).
  • 1 — missing state, Provisioner token failure, no grant found for the Agent Identity/Agent User pair, or a Graph PATCH/DELETE failure.
  • 2 — neither --scopes nor --all was supplied (usage error).
  • --help/-h prints usage and exits 0.

Security

The Provisioner token and certificate material never touch disk or logs. Revocation is immediate on the directory side, but tokens already minted remain valid until they expire.

Common failures

  • Revoking a still-needed scope — later MCP tool calls that rely on it will fail with 403; re-grant with grant_consent.py.
  • Deleting the whole grant — Hop 3 of the three-hop flow can no longer mint a delegated Agent User token until the grant is recreated.