# RevCent MCP Guide: `CreateSecureForm`

AI/MCP-focused guide for creating Secure Forms in RevCent.

This document explains the `CreateSecureForm` operation, its schema, supported form sources, when `form_source_id` is required, how Secure Forms protect sensitive credentials, expiration/completion behavior, and how Secure Forms are used by operations such as User Third Party Integrations and SMTP Profiles.

---

## Operation Summary

Operation:

```text
CreateSecureForm
```

Title:

```text
Create A Secure Form
```

Purpose:

```text
Create a Secure Form that lets the user securely submit sensitive fields so RevCent can encrypt and store them internally.
```

A Secure Form is used when sensitive data must be collected without placing that data inside:

- AI chat,
- MCP request bodies,
- API logs,
- conversation history,
- generated markdown,
- support transcripts,
- external automation logs.

The operation returns:

- `secure_form_id`,
- `form_url`,
- `expiration_date_unix`,
- `completed`,
- source metadata.

The user opens the `form_url`, fills out the sensitive fields, and submits the form. After the user confirms completion, AI/MCP can use the `secure_form_id` in a later operation.

---

## Core Security Rule

Never ask the user to paste credentials or secrets into chat.

Use `CreateSecureForm` for sensitive values such as:

- API keys,
- API secrets,
- usernames,
- passwords,
- SMTP credentials,
- payment gateway credentials,
- fulfillment credentials,
- third-party provider tokens,
- PayPal credentials,
- shop connection credentials,
- any secret required by a RevCent integration.

Correct pattern:

```text
Ask for non-sensitive configuration in chat.
Use CreateSecureForm for sensitive credentials.
Use secure_form_id in the follow-up operation.
```

Incorrect pattern:

```text
Ask the user to paste API keys, passwords, tokens, or secrets into chat.
```

Do not do that.

---

## Why Secure Forms Exist

The operation description explains that Secure Forms are a method to save sensitive data without passing it through a request body where logs and AI conversations should not contain sensitive information.

This is especially important for AI/MCP clients because AI conversations may include generated instructions, request examples, summaries, or logs.

A Secure Form lets RevCent:

```text
Generate a secure form URL
    ↓
User enters sensitive fields directly into RevCent
    ↓
RevCent encrypts/saves the data internally
    ↓
AI/MCP receives only a secure_form_id
    ↓
AI/MCP uses secure_form_id in a later operation
```

The AI/MCP client should never see or store the raw secret values.

---

## Important Expiration Rule

Secure Forms are temporary.

Critical rule:

```text
A Secure Form expires after 1 hour.
```

After expiration:

- the form URL is no longer valid,
- the user cannot complete the form,
- attempts to access the form after expiration return an error,
- the secure form is deleted, including any saved data.

AI/MCP should tell the user they have one hour to complete the form.

If the form expires, create a new Secure Form.

---

## Completion Behavior

The output includes:

```text
completed
```

This indicates whether the user has completed the Secure Form.

When a Secure Form is completed:

```text
The user filled out the form fields.
The form was submitted.
Secure form data was encrypted and saved internally by RevCent.
```

Important:

```text
Once a Secure Form has been completed, it cannot be modified.
```

If the user entered the wrong credentials or needs to change them, create a new Secure Form and use the new `secure_form_id`.

---

## Input Schema

`CreateSecureForm` input schema:

```text
type: object
additionalProperties: false
required:
  - form_source
```

Only send supported fields.

---

## Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `form_source` | string enum | Yes | Source type used to generate the correct secure credential form fields. |

Allowed `form_source` values:

```text
third_party_integration
third_party_shop
gateway
fulfillment_center
smtp_profile
paypal_account
```

---

## Optional Field

| Field | Type | Required Depending On Source | Description |
|---|---:|---:|---|
| `form_source_id` | string | Required for certain source types | 20-character site/source ID used to generate source-specific fields. |

`form_source_id` is applicable only to:

```text
third_party_integration
third_party_shop
gateway
fulfillment_center
```

`form_source_id` is not applicable to:

```text
smtp_profile
paypal_account
```

---

## Form Source ID Map

Use the correct source ID for each source type.

| `form_source` | `form_source_id` Meaning | Required? |
|---|---|---:|
| `third_party_integration` | Site Third Party Integration ID | Yes |
| `third_party_shop` | Site Third Party Shop ID | Yes |
| `gateway` | Site Gateway ID | Yes |
| `fulfillment_center` | Site Fulfillment Center ID | Yes |
| `smtp_profile` | Not applicable | No |
| `paypal_account` | Not applicable | No |

Important:

```text
For third_party_integration, form_source_id is the Site Third Party Integration ID, not the User Third Party Integration ID.
```

---

## Output Schema

Successful output can include:

| Field | Type | Description |
|---|---:|---|
| `api_call_id` | string | 20-character API call ID. |
| `api_call_unix` | integer | Unix timestamp when the API call was initiated. |
| `code` | integer | API response code. `1` indicates success. |
| `secure_form_id` | string | 20-character Secure Form ID. |
| `completed` | boolean | Whether the user has completed and submitted the form. |
| `expiration_date_unix` | integer | Unix timestamp when the form expires. |
| `form_source` | string | Source used to generate the form. |
| `form_source_id` | string | Source ID when applicable. |
| `form_url` | string | URL the user opens to complete the secure form. |
| `result` | string | Result message. |

The user must be logged into RevCent to access the `form_url`.

---

## Basic Request Examples

### Third Party Integration Secure Form

Use this before creating or updating a User Third Party Integration.

```json
{
  "form_source": "third_party_integration",
  "form_source_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

Where:

```text
form_source_id = Site Third Party Integration ID
```

---

### SMTP Profile Secure Form

Use this before creating or updating SMTP Profile credentials.

```json
{
  "form_source": "smtp_profile"
}
```

No `form_source_id` is required.

---

### Gateway Secure Form

Use this before creating or updating payment gateway credentials.

```json
{
  "form_source": "gateway",
  "form_source_id": "GGGGGGGGGGGGGGGGGGGG"
}
```

Where:

```text
form_source_id = Site Gateway ID
```

---

### Fulfillment Center Secure Form

Use this before creating or updating fulfillment center credentials.

```json
{
  "form_source": "fulfillment_center",
  "form_source_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Where:

```text
form_source_id = Site Fulfillment Center ID
```

---

### Third Party Shop Secure Form

Use this before creating or updating a third-party shop connection that requires sensitive fields.

```json
{
  "form_source": "third_party_shop",
  "form_source_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

Where:

```text
form_source_id = Site Third Party Shop ID
```

---

### PayPal Account Secure Form

Use this before creating or updating PayPal account credentials where applicable.

```json
{
  "form_source": "paypal_account"
}
```

No `form_source_id` is required.

---

## Standard Secure Form Workflow

Recommended AI/MCP workflow:

```text
1. Identify the operation that requires sensitive credentials.
2. Determine the correct form_source.
3. Determine whether form_source_id is required.
4. Call CreateSecureForm.
5. Give the user the form_url.
6. Tell the user the form expires in 1 hour.
7. User opens the form_url while logged into RevCent.
8. User fills out and submits the form.
9. User tells AI/MCP the form is complete.
10. AI/MCP uses secure_form_id in the follow-up operation.
```

Example follow-up operations:

- `CreateUserThirdPartyIntegration`,
- `EditUserThirdPartyIntegration`,
- `CreateSMTPProfile`,
- `EditSMTPProfile`,
- gateway-related operations,
- fulfillment center/account operations,
- third-party shop operations,
- PayPal account operations.

---

## Using Secure Forms With User Third Party Integrations

A common use case is connecting a native Site Third Party Integration.

Correct flow:

```text
GetSiteThirdPartyIntegrations
    ↓
GetSiteThirdPartyIntegration
    ↓
CreateSecureForm
        form_source = third_party_integration
        form_source_id = Site Third Party Integration ID
    ↓
User completes form_url
    ↓
CreateUserThirdPartyIntegration with secure_form_id
    ↓
GetUserThirdPartyIntegration
    ↓
If required, EditUserThirdPartyIntegration with third_party_options
```

Example:

```json
{
  "form_source": "third_party_integration",
  "form_source_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

Important:

```text
The form_source_id is the Site Third Party Integration ID.
```

Do not use the User Third Party Integration ID for this source.

---

## Using Secure Forms With EditUserThirdPartyIntegration

Use Secure Form when the user wants to update credentials for an existing User Third Party Integration.

Correct flow:

```text
1. GetUserThirdPartyIntegration.
2. Identify associated Site Third Party Integration ID.
3. CreateSecureForm:
       form_source = third_party_integration
       form_source_id = Site Third Party Integration ID
4. User completes the form.
5. EditUserThirdPartyIntegration with secure_form_id.
6. GetUserThirdPartyIntegration again to verify credentials saved.
```

Example edit request after completion:

```json
{
  "user_third_party_integration_id": "UUUUUUUUUUUUUUUUUUUU",
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Only provide `secure_form_id` if changing credentials.

---

## Using Secure Forms With SMTP Profiles

SMTP credentials must be collected with Secure Form.

Correct create flow:

```text
Collect non-sensitive SMTP settings:
    name
    description
    enabled
    host
    port
    use_ssl
    require_tls
    intended sender/from email or domain
    ↓
CreateSecureForm with form_source = smtp_profile
    ↓
User completes form_url
    ↓
CreateSMTPProfile with secure_form_id
```

Example Secure Form request:

```json
{
  "form_source": "smtp_profile"
}
```

Example create request after completion:

```json
{
  "name": "Main Store SMTP",
  "host": "smtp.example.com",
  "port": 587,
  "use_ssl": false,
  "require_tls": true,
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

For SMTP, do not include `form_source_id`.

---

## Using Secure Forms With EditSMTPProfile

Use Secure Form when changing SMTP credentials.

Correct flow:

```text
1. User explicitly wants to update SMTP credentials.
2. CreateSecureForm with form_source = smtp_profile.
3. User completes the form.
4. EditSMTPProfile with secure_form_id.
```

Example:

```json
{
  "smtp_profile_id": "SSSSSSSSSSSSSSSSSSSS",
  "secure_form_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

Only include `secure_form_id` when credentials are being changed.

---

## Using Secure Forms With Gateways

Gateway credentials should be collected through Secure Form.

Correct flow:

```text
Get site gateway / identify Site Gateway ID
    ↓
CreateSecureForm
        form_source = gateway
        form_source_id = Site Gateway ID
    ↓
User completes form_url
    ↓
Use secure_form_id in gateway create/edit operation
```

Example:

```json
{
  "form_source": "gateway",
  "form_source_id": "GGGGGGGGGGGGGGGGGGGG"
}
```

---

## Using Secure Forms With Fulfillment Centers

Fulfillment center credentials should be collected through Secure Form.

Correct flow:

```text
Identify Site Fulfillment Center ID
    ↓
CreateSecureForm
        form_source = fulfillment_center
        form_source_id = Site Fulfillment Center ID
    ↓
User completes form_url
    ↓
Use secure_form_id in fulfillment create/edit operation
```

Example:

```json
{
  "form_source": "fulfillment_center",
  "form_source_id": "FFFFFFFFFFFFFFFFFFFF"
}
```

---

## Using Secure Forms With Third Party Shops

Third-party shop credentials or sensitive setup values should be collected through Secure Form when required.

Correct flow:

```text
Identify Site Third Party Shop ID
    ↓
CreateSecureForm
        form_source = third_party_shop
        form_source_id = Site Third Party Shop ID
    ↓
User completes form_url
    ↓
Use secure_form_id in shop create/edit operation where supported
```

Example:

```json
{
  "form_source": "third_party_shop",
  "form_source_id": "SSSSSSSSSSSSSSSSSSSS"
}
```

---

## Using Secure Forms With PayPal Accounts

PayPal account credentials/sensitive fields should be collected through Secure Form where applicable.

Correct flow:

```text
CreateSecureForm
    form_source = paypal_account
    ↓
User completes form_url
    ↓
Use secure_form_id in PayPal account create/edit operation where supported
```

Example:

```json
{
  "form_source": "paypal_account"
}
```

No `form_source_id` is required.

---

## What Not to Put in Chat

AI/MCP clients should not ask users to paste:

- SMTP passwords,
- SMTP usernames if sensitive,
- API keys,
- API secrets,
- access tokens,
- refresh tokens,
- OAuth client secrets,
- webhook signing secrets,
- payment gateway credentials,
- shipping provider credentials,
- tax provider API keys,
- third-party shop API secrets,
- PayPal credentials,
- private keys,
- passwords.

Instead, create a Secure Form.

---

## Non-Sensitive Data Can Be Collected Normally

Not everything needs a Secure Form.

AI/MCP can collect non-sensitive configuration in chat, such as:

- integration name,
- description,
- enabled state,
- SMTP host,
- SMTP port,
- SSL/TLS settings,
- intended sender/from email,
- provider name,
- shop/store name,
- campaign scope,
- option choices after provider assets are retrieved,
- public URLs,
- non-secret IDs.

When unsure whether something is secret, use Secure Form or ask the user to enter it in the secure form if the form supports it.

---

## Handling Expired Secure Forms

If a user does not complete the form within one hour:

```text
The Secure Form expires.
The form URL becomes invalid.
The form and saved data are deleted.
```

Correct response:

```text
Create a new Secure Form.
Use the new secure_form_id after completion.
```

Do not reuse an expired `secure_form_id`.

Do not tell the user to keep trying the old form URL after expiration.

---

## Handling Incorrect Form Entries

If the user says they submitted the wrong credentials or wrong values:

```text
Create a new Secure Form.
Have the user complete the new form.
Use the new secure_form_id.
```

Because completed Secure Forms cannot be modified, do not attempt to edit the completed form.

---

## Handling Completion Confirmation

AI/MCP cannot assume the user completed the form just because the Secure Form was created.

Correct flow:

```text
CreateSecureForm returns completed = false
    ↓
User opens form_url
    ↓
User submits form
    ↓
User tells AI/MCP it is complete
    ↓
AI/MCP uses secure_form_id in follow-up operation
```

If the follow-up operation fails due to incomplete/expired form, create a new Secure Form and repeat.

---

## Common Follow-Up Field Names

The follow-up operation usually accepts:

```text
secure_form_id
```

Examples:

| Follow-Up Operation | Field |
|---|---|
| `CreateUserThirdPartyIntegration` | `secure_form_id` |
| `EditUserThirdPartyIntegration` | `secure_form_id` |
| `CreateSMTPProfile` | `secure_form_id` |
| `EditSMTPProfile` | `secure_form_id` |

Other create/edit operations that need sensitive credentials may also use `secure_form_id`.

Always check the target operation schema.

---

## Secure Form Is Not the Final Object

A Secure Form does not itself create the final integration/profile/account.

It only collects and saves encrypted sensitive fields.

You still need to call the follow-up operation.

Example:

```text
CreateSecureForm
    ↓
User completes form
    ↓
CreateSMTPProfile with secure_form_id
```

or:

```text
CreateSecureForm
    ↓
User completes form
    ↓
CreateUserThirdPartyIntegration with secure_form_id
```

Do not stop after creating the Secure Form unless the user's intent was only to generate the form.

---

## Relationship to Third Party Options

Secure Forms handle credentials.

They do not necessarily save provider options/assets.

For User Third Party Integrations:

```text
Secure Form = credentials
third_party_options = provider-specific settings/assets
```

After creating a User Third Party Integration:

```text
GetUserThirdPartyIntegration
    ↓
Review third_party_options and account-specific third-party assets
    ↓
If required, EditUserThirdPartyIntegration with chosen third_party_options
```

Do not confuse credentials with options.

---

## Example: Full Third Party Integration Setup

```text
1. User wants to connect a native tax provider.
2. GetSiteThirdPartyIntegrations.
3. Choose Site Third Party Integration with integration_type = tax.
4. GetSiteThirdPartyIntegration.
5. CreateSecureForm:
       form_source = third_party_integration
       form_source_id = Site Third Party Integration ID
6. User completes secure form.
7. CreateUserThirdPartyIntegration with secure_form_id.
8. GetUserThirdPartyIntegration.
9. If tax provider options/assets exist:
       user chooses option values
       EditUserThirdPartyIntegration with third_party_options
10. CreateTaxProfile using the returned User Third Party Integration ID.
```

---

## Example: Full SMTP Profile Setup

```text
1. User wants to create SMTP Profile.
2. Collect non-sensitive SMTP settings:
       name
       host
       port
       use_ssl
       require_tls
       description
       enabled
3. Confirm sender/from email should match SMTP provider authorization.
4. CreateSecureForm with form_source = smtp_profile.
5. User completes secure form.
6. CreateSMTPProfile with secure_form_id.
7. Create/Edit Email Templates using the returned SMTP Profile ID.
```

---

## Pre-Create Checklist

Before calling `CreateSecureForm`, verify:

- the user needs to submit sensitive data,
- the correct follow-up operation is known,
- the correct `form_source` is selected,
- `form_source_id` is known if required,
- `form_source_id` is not included for `smtp_profile` or `paypal_account`,
- the user understands they must be logged into RevCent,
- the user understands the form expires in one hour,
- the user understands completed forms cannot be modified.

---

## Post-Create Checklist

After calling `CreateSecureForm`, verify:

- `secure_form_id` was returned,
- `form_url` was returned,
- `expiration_date_unix` was returned,
- user received the form URL,
- user knows the one-hour expiration rule,
- AI/MCP waits for user confirmation that the form is completed,
- follow-up operation uses `secure_form_id`,
- if the form expired, a new Secure Form is created.

---

## Best Practices

1. Use Secure Forms for all sensitive credentials.
2. Never ask users to paste secrets into chat.
3. Choose the correct `form_source`.
4. Provide `form_source_id` only when required.
5. Use Site IDs for source-specific forms, not User IDs.
6. Tell the user the form expires in one hour.
7. Wait for user confirmation before using `secure_form_id`.
8. Use the `secure_form_id` only in the intended follow-up operation.
9. Create a new Secure Form if the old one expires.
10. Create a new Secure Form if credentials were entered incorrectly.
11. Do not confuse Secure Forms with third-party options/assets.
12. Verify the follow-up operation after using `secure_form_id`.

---

## Common Mistakes to Avoid

Do not:

- collect API keys, passwords, tokens, or secrets in chat,
- include raw credentials in request examples,
- use `form_source_id` for `smtp_profile`,
- use `form_source_id` for `paypal_account`,
- use a User Third Party Integration ID as `form_source_id` for `third_party_integration`,
- reuse an expired Secure Form,
- assume a form is completed immediately after creation,
- try to modify a completed Secure Form,
- forget to call the follow-up operation,
- confuse credentials with third-party options/assets,
- log or repeat sensitive values.

---

## AI/MCP Decision Guide

| Situation | Correct Action |
|---|---|
| Need to collect third-party integration credentials | `CreateSecureForm` with `form_source = third_party_integration` and Site Third Party Integration ID. |
| Need to collect SMTP credentials | `CreateSecureForm` with `form_source = smtp_profile`. |
| Need to collect gateway credentials | `CreateSecureForm` with `form_source = gateway` and Site Gateway ID. |
| Need to collect fulfillment center credentials | `CreateSecureForm` with `form_source = fulfillment_center` and Site Fulfillment Center ID. |
| Need to collect third-party shop credentials | `CreateSecureForm` with `form_source = third_party_shop` and Site Third Party Shop ID. |
| Need to collect PayPal credentials | `CreateSecureForm` with `form_source = paypal_account`. |
| User completed form | Use `secure_form_id` in the follow-up operation. |
| Form expired | Create a new Secure Form. |
| User entered wrong credentials | Create a new Secure Form. |
| Need to configure provider options/assets | Use `GetUserThirdPartyIntegration`, then `EditUserThirdPartyIntegration` with `third_party_options`. |

---

## Final AI/MCP Instruction

Use `CreateSecureForm` whenever sensitive credential fields must be collected for RevCent operations.

The operation creates a temporary Secure Form, returns a `form_url`, and provides a `secure_form_id` that can be used in a follow-up operation after the user completes the form. The user must be logged into RevCent to access the form URL.

Secure Forms expire after one hour. Completed Secure Forms cannot be modified. If the form expires or the user submits incorrect credentials, create a new Secure Form.

Do not ask users to paste secrets into chat. Use Secure Forms for credentials, then use `secure_form_id` in operations such as `CreateUserThirdPartyIntegration`, `EditUserThirdPartyIntegration`, `CreateSMTPProfile`, `EditSMTPProfile`, and other credential-dependent create/edit operations.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.