> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textmine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent self-service signup

> Self-serve onboarding for third-party agents that need a TextMine organization, service-account API key, billing, Public API V3, and MCP access.

**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](/integrations/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://mcp.textmine.com/mcp`                                              | Central 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.

## How signup is enabled

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.

## Submit self-service signup

When signup is available, call:

```http theme={null}
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.

## What signup creates

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](/vault/overview), [Scribe](/scribe/overview), [Agents](/agents/overview), [Workflows](/workflows/overview), and [Playbooks](/playbooks/overview).
* 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:

```bash theme={null}
curl "<TEXTMINE_PUBLIC_API_BASE_URL>/v3/..." \
  -H "Authorization: Bearer $TEXTMINE_API_KEY" \
  -H "Content-Type: application/json"
```

The same credential can call the central TextMine MCP server:

```text theme={null}
POST https://mcp.textmine.com/mcp
Authorization: Bearer tm_<key>
Accept: application/json,text/event-stream
```

Use `X-TextMine-Api-Key: tm_<key>` only for connector platforms that own the `Authorization` header. 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](/vault/overview), [document types](/vault/document-types-and-tags), [workflows](/workflows/overview), [records](/records/overview), [agents](/agents/overview), and other resources the external agent can access.

The discovery metadata also declares an alternate API-key header:

```text theme={null}
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:

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

Optional setup depends on what the agent will do:

* Configure [Playbooks](/playbooks/overview) before running review, redline, or playbook-rule checks.
* Create or select [Workflows](/workflows/overview) before invoking workflow automation.
* Create clear task instructions before using [task agents](/agents/overview).
* Connect MCP clients or the [TextMine CLI](/integrations/textmine-cli) 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](/vault/overview), [workflow execution](/workflows/overview), [Workbench tasks](/workbench/overview), and [agent tasks](/agents/overview).

When the free allowance is exhausted, API-key usage that requires more credits can return `402 Payment Required`. The agent should then:

1. 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.
2. Call `POST /v3/agent-billing/checkout` to create a Stripe Checkout session.
3. Send the returned checkout URL to the billing owner or show it in the agent's billing UI.
4. 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](/vault/overview), [document type setup](/vault/document-types-and-tags), [workflows](/workflows/overview), 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, central MCP URL, and API key must belong to the same TextMine environment or be routed by TextMine for that 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.