Skip to content

The pending MCP connection request, for the consent page

GET
/connected-apps/requests/{requestId}
curl --request GET \
--url https://api.tovarifinancial.com/connected-apps/requests/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
--header 'Authorization: Bearer <token>'

KAN-4116. The OAuth client asking for access (KAN-4179: read, or read and the opt-in write) and the caller-scoped status of the request. Client strings are data only, clientUri / logoUri only when https; verified for a pre-registered verified client or (KAN-4174) a proven non-loopback domain on the operator allowlist (claude.ai, claude.com, chatgpt.com, exact host); scopeDescription is server copy in the reader’s language. KAN-4118 adds client.domain (the proven hostname) and household.name (the household the app will read). KAN-4174 adds grantDays, how long approved access lasts (90 verified, 7 otherwise). SUBSCRIPTION-EXEMPT: a lapsed member can still see and refuse a request. Verification- and policy-gated. Answers 404 NOT_FOUND while the MCP server is not armed (MCP_SERVER_ENABLED).

requestId
required
string format: uuid

The authorization request id GET /oauth/authorize put on the consent URL.

The request

Media typeapplication/json
object
data
required
object
requestId
required
string format: uuid
client
required
object
clientId
required
string
name
required
string
nullable
clientUri
required
string
nullable
logoUri
required
string
nullable
redirectHost
required
string
source
required
string
Allowed values: cimd dcr static
verified
required
boolean
domain
required
object
host
required

Hostname only — never a path, port, query or full URL.

string
kind
required

client_metadata: the CIMD client_id URL host; redirect: the redirect URI host; loopback: a native app’s 127.0.0.1 / [::1] / localhost redirect.

string
Allowed values: client_metadata redirect loopback
household
required
object
name
required

The session household’s name; null for an unnamed (placeholder) household — the client renders its own fallback.

string
nullable
scope
required

What the app asked for (KAN-4179: write always implies read). Kept one release beside scopes.

string
Allowed values: tovari.read tovari.read tovari.write
scopeDescription
required

The read permission’s wording (= scopes.read.description). Kept one release.

string
writeRequested
required

KAN-4179. The app asked to make changes: render the unticked “Make changes” opt-in.

boolean
scopes
required
object
read
required
object
description
required
string
write
required

Non-null only when writeRequested.

object
description
required
string
grantedScope
required

What the caller granted, once approved (KAN-4179); null while pending or denied.

string
nullable
Allowed values: tovari.read tovari.read tovari.write
grantDays
required

How many days approved access would last: 90 for a verified client, 7 otherwise (KAN-4174).

integer
Allowed values: 7 90
expiresAt
required
string format: date-time
status
required
string
Allowed values: pending approved denied consumed
message
string
requestId
required
string
timestamp
required
string format: date-time
Example
{
"data": {
"client": {
"source": "cimd",
"domain": {
"kind": "client_metadata"
}
},
"scope": "tovari.read",
"grantedScope": "tovari.read",
"grantDays": 7,
"status": "pending"
}
}

Missing, invalid, or expired bearer token

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}

Authenticated, but the tenant gate refuses the request until the caller resolves a precondition. errorCode is one of EMAIL_NOT_VERIFIED, POLICY_ACCEPTANCE_REQUIRED, or SUBSCRIPTION_REQUIRED, evaluated in exactly that order (contract term CCR-1: email verification first, then policy acceptance, then subscription — so a subscriber who has merely not re-accepted the current policies always sees POLICY_ACCEPTANCE_REQUIRED). A POLICY_ACCEPTANCE_REQUIRED body additionally carries details.outstanding (the policy versions still to accept) and details.firstAcceptance. The SUBSCRIPTION_REQUIRED arm is INERT unless the server-side BILLING_ENABLED flag is exactly the string true; while it is off, only the first two codes are reachable. Not retryable as sent — resolve the named condition, then resend.

Media typeapplication/json
object
errorCode
required

Which precondition refused the request. Evaluated in this order (CCR-1); SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true.

string
Allowed values: EMAIL_NOT_VERIFIED POLICY_ACCEPTANCE_REQUIRED SUBSCRIPTION_REQUIRED
message
required
string
details
object
outstanding
required

Active policy versions the user has not yet accepted.

Array<object>
object
id
required
string format: uuid
policyType
required
string
version
required
integer
title
required
string
firstAcceptance
required

True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.

boolean
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "EMAIL_NOT_VERIFIED"
}

MCP_AUTHORIZATION_REQUEST_INVALID — unknown request, or still pending past its 10-minute expiry

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}

MCP_AUTHORIZATION_REQUEST_DECIDED — the request was already decided (by another member or household, or the opposite way by the caller)

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}

Internal error (no internal detail leaked)

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}

Service temporarily unavailable — errorCode is SERVICE_UNAVAILABLE. A TRANSIENT, RETRYABLE condition rather than a defect in the request: a query that exceeded its time budget, a lost or refused database connection, a saturated connection pool, or an outage at an upstream provider the request depends on (the authentication provider, or the bank data provider on a bank-connection operation). The identical request may succeed on retry — back off briefly and, on a write, resend the same X-Idempotency-Key where the operation accepts one.

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}