Skip to content
ApiqDevelopers
API v1.64.0Open console
API referenceidentity

Lookup mcp grant request

POST/v1/mcp/grant-requests:lookup
Accepts bearer

Find a pending console device-flow grant by the code the human typed (RFC 8628 section 3.3)

HUMAN CONSOLE SESSION ONLY (a key, service token or grant-derived token is 403 PERMISSION_DENIED SESSION_REQUIRED).Show moreHUMAN CONSOLE SESSION ONLY (a key, service token or grant-derived token is 403 PERMISSION_DENIED SESSION_REQUIRED). The console's Connect page posts the user_code the human typed; the code travels in the body so it never reaches a URL or an access log. Case and the dash are ignored. Answers the same McpGrantRequest as getMcpGrantRequest, flow DEVICE_CODE, with requesterIpCountry. An unknown, expired, spent or supplier-realm code is 404 NOT_FOUND details.reason USER_CODE_UNKNOWN (one answer, so codes cannot be probed). Lookups are rate limited per session and per client address: 429 RATE_LIMITED.

Request bodyMcpGrantRequestLookup

  • userCodestringRequired
    The code the human typed; case and the dash are ignored

Responses

  • 200The pending requestMcpGrantRequest
  • 400VALIDATION or UNKNOWN_DOMAINApiErrorResponse
  • 401
    UNAUTHENTICATED — missing or expired token.Show moreUNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
    ApiErrorResponse
  • 403
    PERMISSION_DENIED details.reason SESSION_REQUIRED on the MCP consent routes (/v1/mcp/grant-requests/*, /supplier/v1/mcp/grant-requests/*, /ops/v1/mcp/grant-requests/*): only a signed-in human of the…Show morePERMISSION_DENIED details.reason SESSION_REQUIRED on the MCP consent routes (/v1/mcp/grant-requests/*, /supplier/v1/mcp/grant-requests/*, /ops/v1/mcp/grant-requests/*): only a signed-in human of the realm reads or decides a grant request. An API key, a service token and an MCP grant-derived token (details.credential mcp-grant) are all refused, so an agent never reads or approves its own consent.
    ApiErrorResponse
  • 404
    NOT_FOUND details.reason USER_CODE_UNKNOWN — no pending device-flow request of this realm matches the code (unknown, expired, already used, or another realm's).Show moreNOT_FOUND details.reason USER_CODE_UNKNOWN — no pending device-flow request of this realm matches the code (unknown, expired, already used, or another realm's). One answer for all four, so codes cannot be probed.
    ApiErrorResponse
  • 405
    VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show moreVALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
    ApiErrorResponse
  • 413
    VALIDATION — the request body is larger than the surface's limit.Show moreVALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
    ApiErrorResponse
  • 414
    VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show moreVALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
    ApiErrorResponse
  • 415
    VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show moreVALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
    ApiErrorResponse
  • 429
    RATE_LIMITED — the API key or its tenant is over a rate limit; wait for Retry-After, then retry.Show moreRATE_LIMITED — the API key or its tenant is over a rate limit; wait for Retry-After, then retry. Every routed request is counted against two token buckets, the key's and the tenant's (all its keys together): 50 requests a second with a burst of 100 on the standard plan. Every travel verb except polling a search also spends from a supplier budget, per key and per tenant: 10 requests a second with a burst of 20, and a plan may add a daily quota of supplier calls. Answers carry the IETF RateLimit header fields for the tightest bucket consulted (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy); a refusal adds Retry-After and details.scope (KEY or TENANT), details.budget (PLATFORM or SUPPLIER), details.reason (RATE or DAILY_QUOTA), details.tier and details.retryAfterMs. A sandbox may run with the limiter off, in which case none of these headers is sent. A search that is still warming is a different answer with a different meaning (keep polling). with the key-velocity check on, also details.reason VELOCITY_LIMIT, a soft breach of the API key's own scope (components/responses/VelocityLimited), nextAction slow_down.
    ApiErrorResponse
  • 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

400VALIDATION
message.intent.checkOut must be after message.intent.checkIn
not retryable
400UNKNOWN_DOMAIN
Unknown domain 'HOTELS'. Did you mean HTL?
not retryable
401UNAUTHENTICATED
The bearer token is expired. Re-authenticate and retry.
not retryable
403PERMISSION_DENIED
Approving agent connections needs a signed-in person. An agent cannot read or approve its own connection.
not retryable
404NOT_FOUND
No pending agent connection matches that code. Check the code on the agent's screen or start again there.
not retryable
405VALIDATION
This method is not served.
not retryable
413VALIDATION
The request body is larger than this API accepts (262144 bytes).
not retryable
414VALIDATION
The request URI is longer than 8 KiB.
not retryable
415VALIDATION
Send application/json.
not retryable
429RATE_LIMITED
Too many requests for this key on the supplier budget. Wait for the Retry-After interval before trying again.
retryable
500INTERNAL
An unexpected error occurred. Quote the traceId to support.
retryable