POST/memory/revoke

Revoke Access

Revoke access to memories using a revocation token. Once revoked, subsequent read operations for the same scope and domain will return empty results.

Authentication

All requests require authentication via the X-API-Key header.

User Privacy Control

Revocation tokens give users complete control over their data. When a user revokes access, the data becomes immediately unavailable for subsequent reads. This is essential for GDPR compliance and user trust. See Revocation Tokens for more information.

Request Body

Request Schema

{
  "revocation_token": "string (required) - The revocation token from a read operation"
}

Field Descriptions

revocation_token - The revocation token returned from a /memory/read operation. This token identifies the read grant to revoke.

Example Request

from memory_scope import MemoryScopeClient

client = MemoryScopeClient(api_key="your-api-key")

# First, read memories to get a revocation token
result = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate food recommendations"
)

revocation_token = result.revocation_token

# Later, when user wants to revoke access
client.revoke_memory(revocation_token=revocation_token)

# Subsequent reads will return empty results
result = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate food recommendations"
)

print(result.summary_struct)
# {} - Empty because access was revoked

Response

Status Code: 200 OK

Success Response

{
  "revoked": true,
  "revoked_at": "2026-01-27T10:20:15Z"
}

Response Fields

revoked - Always true on successful revocation.
revoked_at - The timestamp when the revocation occurred.

Error Responses

400 Bad Request

Invalid request body or missing required fields.

{
  "detail": "Field 'revocation_token' is required"
}

401 Unauthorized

Invalid or missing API key.

{
  "detail": "Invalid API key"
}

404 Not Found

The revocation token is invalid, expired, or has already been revoked.

{
  "detail": "Revocation token not found"
}

What Happens After Revocation?

Once a revocation token is revoked, the following occurs:

Immediate Effect: The revocation takes effect immediately. No delay or grace period.
Subsequent Reads: Any subsequent read operations for the same user, scope, and domain will return empty results (empty summary_struct).
Continue Operations: Any attempts to use the revoked token with /memory/read/continue will fail with a 404 error.
New Memories: If new memories are created after revocation, they can be read normally with a new read operation.
Audit Logging: The revocation is logged in the audit trail for compliance purposes.

Use Cases

User Data Deletion

When a user requests data deletion (GDPR right to be forgotten), revoke all revocation tokens associated with that user to immediately stop access to their data.

Withdraw Consent

If a user withdraws consent for data processing, revoke the relevant tokens to stop further access.

Security Incident

In case of a security incident or suspected unauthorized access, revoke tokens to immediately stop access to affected data.

Best Practices

Provide User Control: Always provide users with a way to revoke access through your application UI (e.g., "Delete my data" or "Revoke access" button).
Store Tokens Securely: Keep revocation tokens securely associated with user sessions so users can revoke their own data.
Handle Gracefully: When data is revoked, handle the empty results gracefully in your application - show appropriate messages to users.
Respect User Choice: Once a user revokes access, don't attempt to re-read the data or create new read grants without explicit user consent.
Compliance: Revocation is essential for GDPR compliance. Ensure your application supports user data deletion requests.
Audit Trail: All revocations are logged. Review audit logs periodically to ensure compliance.