Revocation Tokens

Every read operation returns a revocation token that gives users complete control over their data. Users can revoke access at any time, ensuring privacy and compliance.

What are Revocation Tokens?

A revocation token is a unique identifier returned with every successful read operation. This token represents a "grant" of access to the data that was read. Users can use this token to immediately revoke access, ensuring they have complete control over their data.

Privacy First

Revocation tokens are a core privacy feature. They give users the ability to withdraw consent and revoke access to their data at any time, which is essential for GDPR compliance and user trust.

How Revocation Works

Read Operation: When you read memories, the API returns a revocation token along with the data.
Token Storage: Store the revocation token securely and associate it with the user session or request.
User Revocation: When a user wants to revoke access, call the revoke endpoint with the token.
Immediate Effect: Once revoked, subsequent read operations for the same scope and domain will return empty results until new memories are created.

Example: Using Revocation Tokens

Revocation Example

from memory_scope import MemoryScopeClient

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

# Read memories - get revocation token
result = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate food recommendations"
)

print(f"Data: {result.summary_struct}")
print(f"Revocation token: {result.revocation_token}")

# Store the token for later use
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

Token Expiration

Revocation tokens have an expiration time (typically 24 hours). After expiration, the token can no longer be used to revoke access, but the grant itself may still be active depending on your application's logic.

The expiration time is included in the read response as expires_at. Use this to determine when a token will expire.

{
  "revocation_token": "rev_xyz789...",
  "expires_at": "2026-01-28T10:15:24Z"
}

You can use an existing revocation token to continue reading memories without creating a new grant. This is useful when you need to re-read the same data multiple times.

Continue Reading Example

# First read - get token
result = client.read_memory(
    user_id="user123",
    scope="preferences",
    domain="food",
    purpose="generate food recommendations"
)
token = result.revocation_token

# Continue reading with the same token
result = client.read_memory_continue(revocation_token=token)

# Same data, no new grant created

Security Considerations

Store Securely: Revocation tokens should be stored securely and associated with the user who owns the data.
One-Time Use: While tokens can be used for continue operations, they should be treated as sensitive and not exposed in URLs or logs.
User Control: Always provide users with a way to revoke access, such as a "Delete my data" or "Revoke access" button in your UI.
Audit Trail: All revocation operations are logged in the audit trail for compliance.

Best Practices

Store with User Session: Associate revocation tokens with user sessions so users can revoke their own data.
Provide Revocation UI: Make it easy for users to revoke access through your application interface.
Handle Revoked State: Gracefully handle cases where data has been revoked - show appropriate messages to users.
Respect User Choice: When a user revokes access, respect their decision and don't attempt to re-read the data.
Compliance: Revocation tokens are essential for GDPR compliance - ensure your application supports user data deletion requests.