Authentication and permissions

Browser consent with PKCE

Askdepth uses OAuth Authorization Code with PKCE S256 for public MCP clients. Codex and Claude Code manage this flow for you. No static Askdepth API key or client secret is required.

1. The client discovers the authorization server from the protected resource metadata.
2. It registers a public OAuth client and valid redirect URI.
3. It opens authorization with the exact workspace resource URL, scopes, state, and PKCE challenge.
4. You sign in to Askdepth and approve the displayed workspace and permitted scopes.
5. The client exchanges the one-use code and matching verifier for an access token and rotating refresh token.

The protected resource metadata is at /.well-known/oauth-protected-resource/mcp/workspaces/<workspace-slug> on the endpoint origin. The authorization server advertises its authorization, registration, token, and revocation endpoints. Discover these endpoints rather than assuming a hostname.

Custom client parameters

Dynamic registration accepts redirect_uris (1–10 URLs), an optional client_name (1–100 characters, default Local coding client), and optional standard public-client metadata: token_endpoint_auth_method: "none", grant_types containing authorization_code and/or refresh_token, and response_types containing code.

Redirects must use HTTPS, except HTTP loopback addresses are supported for local clients. Credentials and fragments are rejected. HTTP loopback port changes are permitted when the remaining registered redirect URI matches; other redirect URIs must match exactly.

Authorization requires:

Token requests use application/x-www-form-urlencoded. For a code exchange, send grant_type=authorization_code, client_id, resource, code, redirect_uri, and code_verifier. For refresh, send grant_type=refresh_token, client_id, resource, and refresh_token; an optional scope may narrow access.

Illustrative token response:

{
  "access_token": "<opaque-access-token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<opaque-refresh-token>",
  "scope": "workspace:read tasks:read implementation:write"
}

Send access tokens only in the Authorization: Bearer header. A token for one workspace cannot be used against another workspace endpoint.

Scopes and roles

Viewers see completed research and research-linked tasks from completed, undeleted research. Write access is checked against the live role, not only the role at consent time. Workspace membership, grant validity, and workspace plan eligibility are also rechecked. A role change can remove access from an existing connection.

The workspace must have an eligible plan with the AskClaw feature. If setup or consent shows a plan restriction, ask a workspace owner or admin to review availability. This documentation does not imply that every plan or deployment has MCP enabled.

Expiry and rotation

Replace the refresh token after each successful refresh. Reusing a consumed refresh token revokes the grant. Refreshing does not extend the original grant's 30-day lifetime; sign in and consent again after expiry. Serialize refreshes for the same stored credential to avoid accidental replay.

Revoke and reconnect

On Askdepth's MCP page, every member can revoke their own connection. Owners and admins can revoke other workspace connections. Revocation remains available when MCP is disabled. A custom client can also use the discovered revocation endpoint with token, client_id, and an optional token_type_hint of access_token or refresh_token; revocation invalidates the associated grant.

Revoking a grant prevents further tool access, but does not stop a coding process already running on your machine. A new login creates a different grant. It cannot report into a run claimed by the old grant: release the old run and create a new attempt when necessary.