Connect Tallyhand to your applications

Tallyhand uses Clerk as its OAuth authorization server. The application receives delegated access to the consenting user’s Tallyhand workspace. Creating a client is not an account grant, and Tallyhand is not a general-purpose identity provider for unrelated products.

Executor

1. Open Settings → Connect → OAuth applications while signed in.
2. Choose the Executor preset. Its callback must match exactly: https://v2.executor.sh/api/oauth/callback.
3. Choose allowed permissions. For full workspace control select read, write, manage and offline access. Confidential server applications use a client secret and S256 PKCE; public native/browser applications use S256 PKCE without a secret.
4. Create the client and copy its ID and one-time secret directly into Executor. Do not paste secrets into chats.
5. In Executor’s OAuth provider definition, request the same desired scopes. A form displaying only tally:read offline_access requests read-only access. Registering more allowed scopes does not upgrade that request.
6. Connect, sign in to Tallyhand and review the consent screen. If you change requested scopes later, authorize the expanded grant before attempting writes.

Permissions and discovery

• tally:read: read workspace data.
• tally:write: create and edit records.
• tally:manage: consequential bookkeeping actions such as deletion, sending invoices, marking payment recorded and managing public links. It does not execute bank transfers.
• offline_access: request refresh tokens from the authorization server. This is a token-lifecycle permission, not a workspace API permission.

MCP endpoint and OAuth resource/audience: https://tallyhand.xyz/api/mcp. Read protected-resource metadata to discover the authorization server. Fetch that issuer’s OAuth metadata for authorization, token and supported client-registration methods. Supply the exact resource in both authorization and token requests. Keep state and S256 PKCE verification enabled.

For another deployment, substitute its own MCP resource URL. Never forward Tallyhand credentials to a different host or disable audience checks to fix an integration.

REST API, CLI and agent skills

For Grok Bots and other agents, use the standalone Tallyhand SKILL.md. It is one Markdown file with setup and workflow instructions; it does not require a plugin bundle or grant account access.

Create a Grok Bot template

1. Create a bot named Tallyhand whose job is to track contractor work and prepare invoice drafts.
2. Ask it to read https://tallyhand.xyz/SKILL.md and save the instructions as a skill named Tallyhand. Connect your account through supported MCP/OAuth, the CLI, or the web app.
3. Test a read-only setup review, then a time-entry and invoice-draft workflow using synthetic records. Keep public sharing disabled for the draft.
4. Open the bot’s Share menu, choose Create template, and review View template details. Remove credentials, customer data, private links, and account-specific configuration.
5. Choose Public link and Copy link. Use that actual generated URL for your Exhibit submission. Every recipient must connect their own Tallyhand account.

Grok Bot template sharing · Saving skills and testing routines

The REST workspace API is at https://tallyhand.xyz/api/v1. Personal API keys and resource-bound OAuth access tokens use the Authorization: Bearer header. Read the OpenAPI contract for endpoints, request schemas, pagination, idempotency and dry-run previews. Credential management and OAuth-client administration require browser sign-in.

The tally CLI installs as a standalone binary using the setup guide; it is not published on npm. Run tally login to enter a personal API key privately, tally doctor to verify access and tally --help to discover commands. Environment variables TALLYHAND_API_URL and TALLYHAND_API_TOKEN support automation. Local stdio MCP uses tally mcp.

Public discovery files include the integration declaration, API catalog, MCP server card, agent guide and five workflow skills. Verify each skill archive’s SHA-256 digest before using its instructions. These files describe available access; they do not grant workspace permissions.

Client management

Only the signed-in owner can list or delete clients they created here, or rotate their secrets. Existing ChatGPT clients and administrator-created clients are not imported into this list. API keys and OAuth bearer tokens cannot administer OAuth clients. Deleting an application disrupts connections using it; secret rotation requires updating the connecting application.

Client ownership IDs are stored in private Clerk user metadata. Credentials and grants remain with Clerk. The client secret is returned only during creation or rotation and is not stored by Tallyhand. Keep the secret in your application’s server-side secret store.

Troubleshooting

• Manual-client form: register a client here. Automatic registration depends on both the host’s implementation and the authorization server’s advertised capabilities.
• Invalid scope: check that Clerk supports the custom tally scopes and offline access, and that the connecting client requests them.
• Invalid audience or unauthorized: use the exact MCP resource URL in the OAuth requests. A Clerk browser-session JWT is not a substitute for an OAuth access token.
• Provider configuration error: the administrator must enable consent and require PKCE in Clerk. Tallyhand refuses to publish an unsafe registration.
• Only reads work: inspect granted scopes and reauthorize with write/manage. A client cannot promote its own token.

Webhooks

General outbound workspace-event webhooks are not available in this release. OAuth callbacks are not webhook delivery endpoints. Do not configure a webhook URL expecting invoice or timesheet events yet; use authenticated API reads until signed event delivery is implemented.

Executor connection documentation · Clerk OAuth documentation