Skip to main content
POST
Check an application registration proposal
Pending coordinated release. This checks a proposal; it does not register an app or make its origins trusted. Discover tool availability in your connected host before use.
Before connecting an external app, check its proposed name, environment, origins and return URLs. A successful result means those values passed validation for the selected workspace. It does not prove domain ownership.

What happens

The preflight runs after normal Recoup authentication. First-time sign-in can perform normal account provisioning and send its welcome email. After that, this validator does not persist an application or issue application credentials. It does not edit provider callbacks, create fan identities or sessions, allocate capacity, or authorize purchases and spending. workspace_id and billing_owner_id come from the authenticated account or an organization it can access. They describe the proposed owner only. Supplying organization_id does not grant workspace access. Do not submit account or billing ownership overrides, secrets or tokens in the proposal. The result is flat and includes status: "validated", persisted: false and origins_verified: false. It contains no application ID or token to install.

Addresses and environments

  • Choose development or production explicitly for each proposal.
  • Use exact canonical origins such as https://music.example, without a trailing slash, wildcard, path, credentials, query or fragment. Different hosts and ports are different origins.
  • HTTPS is required. Development also accepts HTTP on localhost, 127.0.0.1 and [::1]; these loopback hosts are rejected in production.
  • A return URL must be an exact canonical URL on one of the proposed origins, without credentials or fragments. For a bare host use its canonical trailing slash, such as https://music.example/. Query strings are retained literally.
  • Each list takes 1–32 distinct addresses, each at most 2048 characters. The name is trimmed and must then contain 1–120 characters. These are input limits, not subscription or usage allowances.
Matching a return URL to a caller-proposed origin does not establish that the caller owns either address. No DNS check, URL fetch or domain proof is performed.

Standard MCP

On a standard API-key MCP connection that exposes validate_application_registration, use the same proposal fields as HTTP. Account identity comes from the connection; do not add account_id or extract a host-managed OAuth token.
Delegated OAuth excludes this tool, including connections with mcp:tools. HTTP and standard MCP share proposal validation; their transport-specific error envelopes differ. HTTP authentication errors can use error or message, while handled preflight errors use status: "error" and error. MCP failures are tool errors or SDK input-validation errors. None confirms registration or activation. See authentication and MCP connection guidance. Application persistence, origin proof/reverification, provider configuration, fan bootstrap, suspension and quota policy require their own completed contracts.

Authorizations

x-api-key
string
header
required

Body

application/json
name
string
required

Whitespace is trimmed before requiring 1–120 characters. The response returns the trimmed name.

Minimum string length: 1
environment
enum<string>
required

Required; this proposal checks one environment. This does not create environment resources or allowances.

Available options:
development,
production
allowed_origins
string<uri>[]
required

Distinct canonical exact origins, including the scheme and any non-default port. No wildcard, path, trailing slash, credentials, query or fragment. HTTPS is required; HTTP localhost, 127.0.0.1 and [::1] are accepted only in development. Those three hostnames are rejected in production. A proposed origin does not prove domain ownership.

Required array length: 1 - 32 elements
Required string length: 1 - 2048
return_urls
string<uri>[]
required

Distinct exact canonical URLs whose origin matches one of allowed_origins. Credentials and fragments are rejected. Include the URL parser’s trailing slash for a bare host. Query strings are retained literally, not used as patterns. Matching a proposed origin does not verify ownership or activate callbacks.

Required array length: 1 - 32 elements
Required string length: 1 - 2048
organization_id
string<uuid>

Optional selected workspace, allowed only for the authenticated account or an organization it may access. Omit for the authenticated account. Caller-supplied account_id and billing_owner_id are rejected.

Response

Proposal accepted by the validator. No application was registered and no domain was verified.

status
string
required
Allowed value: "validated"
persisted
boolean
required

The preflight did not persist an application or registration.

origins_verified
boolean
required

No domain-ownership proof was checked.

workspace_id
string<uuid>
required

Workspace derived from authentication and the authorized optional organization selection.

billing_owner_id
string<uuid>
required

Same proposed owner as workspace_id. Attribution only: no subscription, quota, top-up or spending authority is granted.

name
string
required
Required string length: 1 - 120
environment
enum<string>
required

Required; this proposal checks one environment. This does not create environment resources or allowances.

Available options:
development,
production
allowed_origins
string<uri>[]
required

Distinct canonical exact origins, including the scheme and any non-default port. No wildcard, path, trailing slash, credentials, query or fragment. HTTPS is required; HTTP localhost, 127.0.0.1 and [::1] are accepted only in development. Those three hostnames are rejected in production. A proposed origin does not prove domain ownership.

Required array length: 1 - 32 elements
Required string length: 1 - 2048
return_urls
string<uri>[]
required

Distinct exact canonical URLs whose origin matches one of allowed_origins. Credentials and fragments are rejected. Include the URL parser’s trailing slash for a bare host. Query strings are retained literally, not used as patterns. Matching a proposed origin does not verify ownership or activate callbacks.

Required array length: 1 - 32 elements
Required string length: 1 - 2048