Agent self-service signup - TextMine Documentation

Agent self-service signup provisions a TextMine organization and service-account API credential for an external agent or automation platform that needs to call Public API V3. The TextMine MCP server is optional after the agent has a tm_... API key; signup itself is REST-first and does not require MCP.

Availability: self-service signup is only for TextMine’s multitenant, non-enterprise deployment. Enterprise, private, and customer-dedicated deployments use support-led provisioning instead of the public self-service flow.

Discovery and availability

Agents and automation tools should discover signup state before submitting a signup request.

Endpoint	Purpose
`https://public-api.textmine.com/.well-known/textmine-agent.json`	Public machine-readable discovery document for agent self-service signup, billing, Public API V3, and MCP metadata.
`https://public-api.textmine.com/v3/third-party-agents/signup/discovery`	Public API V3 discovery document with the same setup metadata.
`https://public-api.textmine.com/v3/third-party-agents/signup/availability`	Returns whether self-service signup is currently available and includes terms, privacy, pricing, and setup checklist metadata.

For the UK multitenant deployment, use https://public-api.textmine.com as the Public API base URL. The commonly used signup URLs are:

URL	Purpose
`https://public-api.textmine.com/.well-known/textmine-agent.json`	Public agent discovery document.
`https://public-api.textmine.com/v3/third-party-agents/signup/availability`	Signup availability.
`https://public-api.textmine.com/v3/third-party-agents/signup/discovery`	Public API V3 signup discovery.
`https://public-api.textmine.com/v3/third-party-agents/signup/self-service`	Self-service signup request.
`https://app.textmine.com/mcp`	Hosted TextMine MCP endpoint for the same production environment.

Use the Public API base URL returned by discovery when configuring REST clients. Do not use tenant names or tenant-specific aliases as selectable values for external users; the API key resolves the correct organization.

Machine-readable onboarding

The discovery response is designed for autonomous onboarding. It tells an agent or trusted runtime:

Whether agent self-service signup is available.
Which signup URL and method to use.
Which signup fields, terms acceptance, and privacy acceptance are required.
Which credential-delivery algorithm to use for encrypted API-key return.
Which Public API base URL and MCP endpoint belong to the environment.
How the tm_... API key should be sent after signup.
Which free-credit, billing-status, checkout, and portal endpoints are available.
Which setup checklist steps are required before typed document processing.

Current self-service signup does not require pre-authentication or human verification. It can still be unavailable if the deployment switch, tenant switch, or signup protection settings are disabled. Self-service signup is available only when both are true:

The deployment-level third-party agent switch is enabled.
Tenant-level third-party access is enabled.

Backoffice administrators can view and update tenant-level third-party access from Tenant Settings. If signup is unavailable, check the availability message before trying again. Do not bypass the supported signup flow or reuse an API key from another deployment. When signup is available, call:

POST https://public-api.textmine.com/v3/third-party-agents/signup/self-service

Required request fields:

Field	Description
`organizationName`	Name of the TextMine organization to create for the agent account.
`agentName`	Display name used for the service account and service-account API key.
`contactEmail`	Billing and operational contact email.
`acceptedTerms`	Must be `true`.
`acceptedPrivacy`	Must be `true`.
`credentialDeliveryPublicKey`	RSA public key controlled by the trusted agent runtime, not the model. Accepts PEM or base64-encoded X.509 SubjectPublicKeyInfo.

Optional request fields:

Field	Description
`credentialDeliveryAlgorithm`	Credential delivery algorithm. Defaults to `RSA-OAEP-256`.

The response returns:

organizationId and organizationName.
serviceAccountUserId.
apiKeyId, apiKeyPrefix, and credentialRef.
encryptedApiKey, encryptedApiKeyAlgorithm, and encryptedApiKeyEncoding.
Billing status, free-credit allowance, and currency.
gettingStarted summary.
setupChecklist.

Decrypt encryptedApiKey inside the trusted agent runtime using the private key that matches credentialDeliveryPublicKey. Store the decrypted tm_... API key in a secret store and inject it into future API or MCP calls. Do not place the raw key in model-visible prompts, logs, plans, or task context. The model should only see credentialRef, apiKeyPrefix, and non-secret metadata. Agent task transcripts sanitize secret-like values before persistence. Do not send raw API keys, tokens, passwords, secrets, or credentials in task instructions, messages, context, step input/output, approvals, or events; if they are supplied accidentally, the transcript redactor stores [REDACTED] instead. When signup succeeds, TextMine creates a third-party agent account with:

A corporate TextMine organization for the agent.
The standard feature set needed for agent work: Vault, Scribe, Agents, Workflows, and Playbooks.
An Agent business unit and organization role assignment for the service-account actor.
A service-account user for the third-party agent.
A tm_... service-account API key. For self-service signup, the key is returned as encryptedApiKey encrypted to the trusted runtime’s public key.
An agent billing account with the billing contact email, accepted terms/privacy metadata, free-credit allowance, current-period usage, currency, and purchased credit balance.

The billing contact email is the human owner/contact for billing and support. It is not automatically created as a human TextMine login.

Public API and MCP access

After the trusted runtime decrypts and stores the service-account API key, the third-party agent calls Public API V3 with that credential:

curl "<TEXTMINE_PUBLIC_API_BASE_URL>/v3/..." \
  -H "Authorization: Bearer $TEXTMINE_API_KEY" \
  -H "Content-Type: application/json"

The same credential can call the TextMine MCP server:

POST <TEXTMINE_MCP_URL>
Authorization: Bearer tm_<key>
Accept: application/json,text/event-stream

The Public API base URL is the root host where the agent performed discovery/signup, or the deployment-specific host issued by TextMine. Do not append /v3 when configuring clients such as Zapier; clients append endpoint paths themselves. Public API resolves the key to the service-account actor and the organization created at signup. The key’s organization determines which Vaults, document types, workflows, records, agents, and other resources the external agent can access. The discovery metadata also declares an alternate API-key header:

X-TextMine-Api-Key: tm_<key>

Use the bearer header for Public API and MCP clients unless a platform owns the Authorization header.

First setup steps

The signup response includes a gettingStarted object and setupChecklist. Use those values to drive the agent’s onboarding UI. Before typed document processing, complete the required steps:

Generate a runtime keypair, send credentialDeliveryPublicKey, decrypt encryptedApiKey, and store the API key outside model context.
Accept terms and privacy notices during signup.
Create or select a Vault, or omit vault_id on the first upload so TextMine creates or reuses the default Agent Vault for the API-key organization.
Configure document types, default tags and extraction questions before uploading typed documents.

Optional setup depends on what the agent will do:

Configure Playbooks before running review, redline, or playbook-rule checks.
Create or select Workflows before invoking workflow automation.
Create clear task instructions before using task agents.
Connect MCP clients after the API key is stored in the trusted runtime.

Billing and upgrades

Third-party agent work starts on the configured free-credit allowance for the billing period. Credit costs are returned by the availability and billing-status endpoints, including Vault document processing, workflow execution, Workbench tasks, and agent tasks. When the free allowance is exhausted, API-key usage that requires more credits can return 402 Payment Required. The agent should then:

Call GET /v3/agent-billing/status to show the current billing status, remaining free credits, purchased credit balance, available credits, checkout requirement, setup checklist, and credit-pack metadata.
Call POST /v3/agent-billing/checkout to create a Stripe Checkout session.
Send the returned checkout URL to the billing owner or show it in the agent’s billing UI.
After checkout completes and the purchased credits are added to the organization, continue API work.

Use POST /v3/agent-billing/portal when an existing billed organization needs a Stripe billing portal session. If checkout has not happened yet, the API can require checkout first.

Human access

Self-service signup creates the agent’s organization and service-account API key. It does not automatically create a human user account for the billing owner. If a human user needs to access the TextMine web app for the same organization, contact TextMine support with:

Organization name and organization ID from signup.
Human user’s email address.
Requested access level or role.
Whether the user needs API-key management, Vault setup, document type setup, workflows, or billing support.

After TextMine support links the human user to the organization, the user signs in through the normal TextMine web app. Human users should use their own web session or their own user API key where permitted. Do not share the third-party agent service-account key as a human login credential.

Service accounts and task-agent email

There are two related service-account concepts:

Service-account concept	What it is	How it is enabled
Third-party agent service account	The API actor and `tm_...` key created by third-party agent signup.	Created during signup.
Task-agent service account email route	An organization-level inbound email route that lets organization users create and reply to task-agent tasks by email.	Activated by TextMine support for the organization.

The task-agent email route is separate from the third-party agent API key. It must be activated at the organization level before email can create task-agent work. Third-party agent organizations can have this route too, but it is not automatically enabled just because signup created an API service account. Contact TextMine support to activate or troubleshoot task-agent email routing for a third-party agent organization.

Operational notes

Self-service signup and agent billing are tenant-level capabilities for multitenant, non-enterprise TextMine.
Enterprise or dedicated deployments should use TextMine support-led provisioning.
The Public API base URL, MCP URL, and API key must belong to the same TextMine environment.
The billing contact is not the same thing as the service-account API actor.
Human access, support-managed activation, and task-agent email routing should be requested through TextMine support.
Agents should use idempotency keys where the API supports them, poll asynchronous work, and show resource IDs in user-visible audit summaries.

​Discovery and availability

​Machine-readable onboarding

​How signup is enabled

​Submit self-service signup

​What signup creates

​Public API and MCP access

​First setup steps

​Billing and upgrades

​Human access

​Service accounts and task-agent email

​Operational notes