---
title: "Relinquish a recipient-held grant"
method: POST
path: "/consents/{consentId}/revoke"
tags: ["Consent and data sharing"]
---

# Relinquish a recipient-held grant

`POST /consents/{consentId}/revoke`

## Request

- Base URL: `https://platform-api.homejourney.sg/v1`
- URL: `https://platform-api.homejourney.sg/v1/consents/{consentId}/revoke`
- Auth: HTTP bearer

Lets the recipient organization relinquish a data-sharing grant it holds, failing closed across all access paths. Requires `consents.write`. External URL: `/v1/consents/{consentId}/revoke`. Current Next.js implementation path: `/api/platform/v1/consents/[consentId]/revoke`. This mutating route requires `Idempotency-Key`. Partner API keys can never create or extend user consent; revocation here is recorded with a `partner_api` source.

## Path parameters

- `consentId` string, uuid, required

## Headers

- `X-Correlation-Id` string
- `Idempotency-Key` string, required

## Request body

- RevokePlatformConsentRequest: Optional reason recorded when the recipient relinquishes the grant.
  - `reason` string

## Response `200`

The relinquished grant.

- PlatformConsentDetailResponse
  - `consent` PlatformConsentResource, required: Public-safe view of a data-sharing grant where the calling partner organization is the recipient. Consent text, raw user PII, and internal audit ids are never included.
    - `id` string, uuid, required
    - `environment` 'sandbox' | 'live', required
    - `subject_user_id` string, uuid, required
    - `recipient_type` 'ai_host' | 'marketplace_app' | 'bank' | 'law_firm' | 'agent' | 'agency' | 'service_provider' | 'developer' | 'official_source_operator' | 'internal_operator', required
    - `recipient_organization_id` string, uuid, nullable
    - `recipient_app_id` string, nullable
    - `recipient_client_id` string, uuid, nullable
    - `scope` string, required
    - `data_category` string, required
    - `purpose` string, required
    - `purpose_version` string, required
    - `consent_text_version` string, required
    - `source_channel` string, required
    - `grant_status` 'active' | 'expired' | 'revoked' | 'superseded' | 'suspended', required
    - `is_active` boolean, required
    - `last_used_at` string, date-time, nullable
    - `expires_at` string, date-time, nullable
    - `revoked_at` string, date-time, nullable
    - `revocation_reason` string, nullable
    - `superseded_by_grant_id` string, uuid, nullable
    - `retention_until` string, date-time, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `public_safety` PlatformConsentPublicSafety, required: Redaction guarantees applied to every consent response.
    - `consent_text_returned` false, required
    - `raw_user_pii_returned` false, required
    - `internal_audit_ids_returned` false, required
    - `recipient_billing_returned` false, required
  - `livemode` boolean, required
  - `request_id` string, required

## Other responses

- `400`: Request validation failed.
- `401`: Missing or invalid platform API key.
- `403`: Credential, environment, or scope is not allowed.
- `404`: Platform API feature or resource is not available.
- `409`: Idempotency key is in progress or conflicts with an earlier request body.
- `429`: Rate limit exceeded.
- `500`: Unexpected platform API failure.

---

[API](https://skmtc.dev/homejourney/apis/homejourney-platform-api.md) · [All operations](https://skmtc.dev/homejourney/apis/homejourney-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/homejourney/apis/homejourney-platform-api/revisions/a2c6fe063db1?raw)