# RevCent Secure Forms Overview for AI/MCP

AI/MCP-focused overview for Secure Forms in RevCent.

This document explains what Secure Forms are, why they exist, how they are created and retrieved, how they protect sensitive credential data, how expiration/completion works, and how Secure Forms connect to related RevCent operations such as SMTP Profiles, User Third Party Integrations, gateways, fulfillment centers, third-party shops, and PayPal accounts.

---

## Core Concept

A Secure Form is a temporary RevCent-hosted form used to collect sensitive fields without exposing those fields to AI, MCP, chat, request bodies, logs, or generated documentation.

Simple model:

```text
AI/MCP needs credentials
    ↓
AI/MCP creates Secure Form
    ↓
User opens secure form URL inside RevCent
    ↓
User enters sensitive values directly into RevCent
    ↓
RevCent encrypts and stores the values internally
    ↓
AI/MCP receives and uses only secure_form_id
```

The Secure Form protects secrets such as:

- API keys,
- passwords,
- tokens,
- usernames,
- SMTP credentials,
- payment gateway credentials,
- fulfillment provider credentials,
- third-party shop credentials,
- tax provider credentials,
- shipping provider credentials,
- PayPal credentials,
- other sensitive provider fields.

AI/MCP clients should never ask the user to paste these values into chat.

---

## Why Secure Forms Matter

Secure Forms exist because AI/MCP clients often need to help users create or edit objects that require sensitive authentication data.

Without Secure Forms, sensitive values could end up in:

- AI conversations,
- MCP request bodies,
- API logs,
- debug logs,
- exported markdown,
- user-visible examples,
- support transcripts,
- tool traces.

Secure Forms avoid that problem.

Correct security principle:

```text
Collect non-sensitive setup details in chat.
Collect secrets through Secure Forms.
Reference the completed Secure Form by secure_form_id.
```

The AI/MCP client should never see, repeat, store, summarize, or log the secret values.

---

## Related Operation Links

| Operation | Link | Purpose |
|---|---|---|
| `CreateSecureForm` | `https://revcent.com/documentation/markdown/mcp/operation/CreateSecureForm.md` | Create a temporary Secure Form and receive `secure_form_id` and `form_url`. |
| `GetSecureForm` | `https://revcent.com/documentation/markdown/mcp/operation/GetSecureForm.md` | Retrieve Secure Form status, including `completed`, source, source ID, form URL, and expiration. |

---

## Related Credential-Dependent Operation Links

These operations commonly use Secure Forms or `secure_form_id`.

| Operation / Overview | Link | Why It Matters |
|---|---|---|
| Third Party Integration Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewThirdPartyIntegration.md` | Explains native Site Third Party Integrations and User Third Party Integrations. |
| `CreateUserThirdPartyIntegration` | `https://revcent.com/documentation/markdown/mcp/operation/CreateUserThirdPartyIntegration.md` | Uses `secure_form_id` to save third-party integration credentials. |
| `EditUserThirdPartyIntegration` | `https://revcent.com/documentation/markdown/mcp/operation/EditUserThirdPartyIntegration.md` | Uses `secure_form_id` when changing saved third-party integration credentials. |
| SMTP Profile Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSMTPProfile.md` | Explains SMTP Profiles and secure credential setup. |
| `CreateSMTPProfile` | `https://revcent.com/documentation/markdown/mcp/operation/CreateSMTPProfile.md` | Requires Secure Form for SMTP authentication values. |
| `EditSMTPProfile` | `https://revcent.com/documentation/markdown/mcp/operation/EditSMTPProfile.md` | Uses Secure Form when changing SMTP credentials. |
| Shop Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShop.md` | Third-party shops may require secure setup fields. |
| `CreateUserShop` | `https://revcent.com/documentation/markdown/mcp/operation/CreateUserShop.md` | May use Secure Forms for third-party shop connection credentials where supported. |
| `EditUserShop` | `https://revcent.com/documentation/markdown/mcp/operation/EditUserShop.md` | May use Secure Forms when editing shop connection credentials where supported. |
| Fulfillment Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewFulfillment.md` | Fulfillment accounts may need secure provider credentials. |
| `CreateFulfillmentAccount` | `https://revcent.com/documentation/markdown/mcp/operation/CreateFulfillmentAccount.md` | May use Secure Forms for fulfillment provider credentials. |
| `EditFulfillmentAccount` | `https://revcent.com/documentation/markdown/mcp/operation/EditFulfillmentAccount.md` | May use Secure Forms when changing fulfillment credentials. |
| PayPal Account Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPayPalAccount.md` | PayPal account credentials/sensitive setup values should be handled securely. |
| `CreatePayPalAccount` | `https://revcent.com/documentation/markdown/mcp/operation/CreatePayPalAccount.md` | May use Secure Forms for PayPal account setup where supported. |
| `EditPayPalAccount` | `https://revcent.com/documentation/markdown/mcp/operation/EditPayPalAccount.md` | May use Secure Forms when changing PayPal account credentials. |

Always check the target operation schema before passing `secure_form_id`.

---

## Secure Form Lifecycle

A Secure Form has a short lifecycle.

```text
1. AI/MCP calls CreateSecureForm.
2. RevCent returns secure_form_id and form_url.
3. User opens form_url while logged into RevCent.
4. User enters sensitive fields and submits.
5. RevCent encrypts and saves the sensitive data internally.
6. AI/MCP may call GetSecureForm to verify completed = true.
7. AI/MCP calls the intended follow-up operation with secure_form_id.
```

Important lifecycle rules:

```text
Secure Forms expire after 1 hour.
Completed Secure Forms cannot be modified.
Expired Secure Forms cannot be used.
Incorrect form entries require creating a new Secure Form.
```

---

## CreateSecureForm

Use:

```text
CreateSecureForm
```

to generate a Secure Form.

Required input:

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

Optional input:

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

Allowed `form_source` values:

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

Output includes:

- `secure_form_id`,
- `form_url`,
- `completed`,
- `expiration_date_unix`,
- `form_source`,
- `form_source_id` where applicable.

---

## GetSecureForm

Use:

```text
GetSecureForm
```

to retrieve details of a specific Secure Form.

Required input:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `secure_form_id` | string | Yes | 20-character Secure Form ID. |

Use this operation to check:

- whether the form was completed,
- whether the form is still valid,
- which source it belongs to,
- which source ID it belongs to when applicable,
- form URL,
- creation/update timestamps,
- expiration timestamp.

Most important output field:

```text
completed
```

If `completed = true`, the user submitted the Secure Form and RevCent encrypted/saved the sensitive data internally.

If `completed = false`, do not use the `secure_form_id` yet.

---

## Form Sources

Secure Forms use `form_source` to determine what fields to show.

| `form_source` | Purpose |
|---|---|
| `third_party_integration` | Credentials for a native Site Third Party Integration. |
| `third_party_shop` | Credentials/sensitive setup fields for a Site Third Party Shop. |
| `gateway` | Credentials for a Site Gateway. |
| `fulfillment_center` | Credentials for a Site Fulfillment Center. |
| `smtp_profile` | Fixed SMTP credential form. |
| `paypal_account` | PayPal account credential/sensitive setup form. |

---

## Form Source ID Requirements

Some form sources require `form_source_id`.

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

Important:

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

Do not provide `form_source_id` for `smtp_profile` or `paypal_account`.

---

## Expiration Behavior

A Secure Form expires after one hour.

After expiration:

- the form URL is invalid,
- the user cannot complete the form,
- attempts to access the form return an error,
- the Secure Form is deleted, including any saved data,
- the `secure_form_id` should not be used.

AI/MCP must tell the user:

```text
The secure form expires in one hour.
```

If the form expires:

```text
Create a new Secure Form.
Use the new secure_form_id after the user completes it.
```

---

## Completion Behavior

The `completed` field indicates whether the user submitted the form.

When `completed = true`:

- user filled out required fields,
- user submitted the form,
- RevCent encrypted and saved the sensitive data internally,
- the Secure Form cannot be modified,
- `secure_form_id` can be used in the intended follow-up operation.

When `completed = false`:

- user has not completed the form,
- the form URL can still be used if unexpired,
- do not call the follow-up operation yet.

If the user submitted incorrect credentials:

```text
Create a new Secure Form.
```

Completed Secure Forms cannot be edited.

---

## Secure Form Is Not the Final Object

A Secure Form is only a secure credential-collection step.

It does not itself create:

- SMTP Profile,
- User Third Party Integration,
- Gateway,
- Fulfillment Account,
- User Shop,
- PayPal Account,
- Tax Profile,
- Shipping Profile,
- AI Assistant,
- AI Voice Agent.

After the Secure Form is completed, AI/MCP must call the relevant follow-up create/edit operation with:

```text
secure_form_id
```

Example:

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

or:

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

---

## What Secure Forms Never Return

Secure Forms never return secret values.

Neither `CreateSecureForm` nor `GetSecureForm` returns:

- API keys,
- SMTP passwords,
- access tokens,
- refresh tokens,
- private keys,
- provider secrets,
- payment gateway credentials,
- PayPal credentials,
- shop secrets,
- fulfillment provider secrets.

Secure Form operations return only metadata and identifiers.

The AI/MCP client should never expect to read or display the submitted secret values.

---

## Secure Forms vs Third Party Options

Secure Forms collect credentials.

They do not necessarily configure provider options/assets.

For User Third Party Integrations:

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

Correct full native integration flow:

```text
CreateSecureForm
    ↓
CreateUserThirdPartyIntegration with secure_form_id
    ↓
GetUserThirdPartyIntegration
    ↓
Review account-specific third_party_options/assets
    ↓
EditUserThirdPartyIntegration with selected third_party_options if required
```

Do not confuse credential collection with option selection.

---

## Common Secure Form Workflows

### User Third Party Integration

```text
GetSiteThirdPartyIntegration
    ↓
CreateSecureForm
        form_source = third_party_integration
        form_source_id = Site Third Party Integration ID
    ↓
User completes form_url
    ↓
GetSecureForm verifies completed = true
    ↓
CreateUserThirdPartyIntegration with secure_form_id
    ↓
GetUserThirdPartyIntegration
    ↓
EditUserThirdPartyIntegration with third_party_options if required
```

---

### Updating User Third Party Integration Credentials

```text
GetUserThirdPartyIntegration
    ↓
CreateSecureForm
        form_source = third_party_integration
        form_source_id = associated Site Third Party Integration ID
    ↓
User completes form_url
    ↓
GetSecureForm verifies completed = true
    ↓
EditUserThirdPartyIntegration with secure_form_id
    ↓
GetUserThirdPartyIntegration verifies saved credentials/options
```

Only include `secure_form_id` in `EditUserThirdPartyIntegration` when credentials are being changed.

---

### SMTP Profile Creation

```text
Collect non-sensitive SMTP settings:
    name
    host
    port
    use_ssl
    require_tls
    sender/from email alignment context
    ↓
CreateSecureForm
        form_source = smtp_profile
    ↓
User completes form_url
    ↓
GetSecureForm verifies completed = true
    ↓
CreateSMTPProfile with secure_form_id
```

No `form_source_id` is used for SMTP Profile Secure Forms.

---

### SMTP Credential Update

```text
User wants to change SMTP credentials
    ↓
CreateSecureForm
        form_source = smtp_profile
    ↓
User completes form_url
    ↓
GetSecureForm verifies completed = true
    ↓
EditSMTPProfile with secure_form_id
```

Only include `secure_form_id` in `EditSMTPProfile` when credentials are being changed.

---

### Gateway Credential Setup

```text
Identify Site Gateway ID
    ↓
CreateSecureForm
        form_source = gateway
        form_source_id = Site Gateway ID
    ↓
User completes form_url
    ↓
GetSecureForm verifies completion
    ↓
Use secure_form_id in gateway create/edit operation where supported
```

---

### Fulfillment Center Credential Setup

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

---

### Third Party Shop Credential Setup

```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
    ↓
GetSecureForm verifies completion
    ↓
Use secure_form_id in shop create/edit operation where supported
```

---

### PayPal Account Credential Setup

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

No `form_source_id` is used for PayPal Account Secure Forms.

---

## Non-Sensitive Fields Can Be Collected in Chat

Secure Forms are for sensitive credential fields.

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

- integration name,
- description,
- enabled state,
- SMTP host,
- SMTP port,
- SSL/TLS settings,
- sender/from email,
- provider name,
- shop name,
- campaign scope,
- public URLs,
- non-secret IDs,
- user-selected option values when not secret.

When uncertain whether a value is sensitive, prefer Secure Form or avoid collecting it in chat.

---

## What AI/MCP Should Tell the User

When sending a Secure Form URL, tell the user:

```text
Open this secure RevCent form while logged in.
Enter the sensitive credentials there, not in chat.
The form expires in one hour.
Tell me once you have submitted it.
```

Do not ask the user to paste credentials back into chat.

---

## Error / Edge Case Handling

### Form Not Completed

If `GetSecureForm.completed = false`:

```text
Ask the user to complete the form.
Do not use secure_form_id yet.
```

### Form Expired

If the form expired or cannot be accessed:

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

### Wrong Credentials Submitted

If the user says the wrong credentials were submitted:

```text
Create a new Secure Form.
Use the new secure_form_id in the appropriate create/edit operation.
```

### Wrong Source

If `form_source` or `form_source_id` does not match the intended follow-up operation:

```text
Do not use that secure_form_id.
Create a new Secure Form with the correct source/source ID.
```

### Follow-Up Operation Fails

If a follow-up operation fails because the Secure Form was incomplete or invalid:

```text
Call GetSecureForm if possible.
If incomplete, ask user to complete it.
If expired/invalid, create a new Secure Form.
```

---

## Security Best Practices

1. Never request secrets in chat.
2. Never include secrets in request examples.
3. Never echo secrets back to the user.
4. Use Secure Forms for all credential collection.
5. Use `GetSecureForm` to verify completion before follow-up operations.
6. Confirm `form_source` and `form_source_id` before using a Secure Form.
7. Respect the one-hour expiration window.
8. Create new forms for credential changes or mistakes.
9. Use `secure_form_id` only for the intended operation.
10. Do not use Secure Forms for provider options/assets unless those are sensitive credentials.
11. Keep third-party option selection separate from credential collection.
12. Verify the final object after using `secure_form_id`.

---

## Common Mistakes to Avoid

Do not:

- ask users to paste API keys or passwords into chat,
- use expired Secure Forms,
- use incomplete Secure Forms,
- assume `CreateSecureForm` created the final object,
- assume `GetSecureForm` returns secret values,
- use `form_source_id` for `smtp_profile`,
- use `form_source_id` for `paypal_account`,
- use User Third Party Integration ID as `form_source_id` for `third_party_integration`,
- use one Secure Form for a different source than intended,
- forget the follow-up create/edit operation,
- confuse Secure Form credentials with third-party options/assets,
- try to modify a completed Secure Form.

---

## AI/MCP Decision Guide

| Situation | Correct Action |
|---|---|
| Need sensitive credentials | Use `CreateSecureForm`. |
| Need to check whether user completed the form | Use `GetSecureForm`. |
| `completed = true` | Proceed with intended follow-up operation. |
| `completed = false` | Ask user to complete the form URL. |
| Form expired | Create a new Secure Form. |
| User entered wrong credentials | Create a new Secure Form. |
| Need SMTP credentials | `form_source = smtp_profile`; no `form_source_id`. |
| Need PayPal credentials | `form_source = paypal_account`; no `form_source_id`. |
| Need third-party integration credentials | `form_source = third_party_integration`; `form_source_id = Site Third Party Integration ID`. |
| Need shop credentials | `form_source = third_party_shop`; `form_source_id = Site Third Party Shop ID`. |
| Need gateway credentials | `form_source = gateway`; `form_source_id = Site Gateway ID`. |
| Need fulfillment credentials | `form_source = fulfillment_center`; `form_source_id = Site Fulfillment Center ID`. |
| Need provider options/assets | Use relevant retrieval/edit operations, not Secure Form alone. |

---

## Final AI/MCP Instruction

Secure Forms are RevCent's safe credential-collection mechanism.

Use `CreateSecureForm` whenever sensitive values are required. Give the user the returned `form_url`, tell them to complete it while logged into RevCent, and remind them that the form expires in one hour. Use `GetSecureForm` to verify `completed = true` before using `secure_form_id` in a credential-dependent follow-up operation.

Secure Forms do not create the final integration, SMTP Profile, gateway, fulfillment account, shop, or PayPal account. They only collect and encrypt sensitive fields. After completion, call the intended follow-up operation with `secure_form_id`.

Never ask users to paste secrets into chat. Secure Forms protect users, merchants, RevCent accounts, and AI/MCP workflows from leaking credentials into logs or conversations.


---
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.