> ## Documentation Index
> Fetch the complete documentation index at: https://core.anylayer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Revoke Attestation

> Revoke an existing attestation

## Overview

Revoke an existing attestation that you have issued. This endpoint allows attestation issuers to revoke their attestations when circumstances change, providing a mechanism for maintaining the integrity of the trust system.

<Tip>
  Use this endpoint to revoke attestations when relationships change, skills become outdated, or when you need to correct erroneous attestations. Only the original issuer can revoke an attestation.
</Tip>

## Parameters

<ParamField path="attestationId" type="string" required>
  Unique identifier of the attestation to revoke
</ParamField>

## Request Body

<ParamField body="reason" type="string" required>
  Reason for revoking the attestation

  * `relationship_ended` - Relationship has ended
  * `skill_outdated` - Skill is no longer current
  * `achievement_invalid` - Achievement was incorrectly awarded
  * `reputation_changed` - Reputation has changed
  * `identity_verification_failed` - Identity verification failed
  * `other` - Other reason (specify in details)
</ParamField>

<ParamField body="details" type="string">
  Additional details about the revocation reason
</ParamField>

<ParamField body="signature" type="string" required>
  Cryptographic signature proving ownership of the attestation
</ParamField>

<ParamField body="notifySubject" type="boolean">
  Whether to notify the subject about the revocation (default: true)
</ParamField>

<ParamField body="publicReason" type="string">
  Public reason for the revocation (visible to others)
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the attestation was revoked successfully
</ResponseField>

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="attestationId" type="string">
  Identifier of the revoked attestation
</ResponseField>

<ResponseField name="attestation" type="object">
  Revoked attestation details

  <Expandable title="attestation properties">
    <ResponseField name="id" type="string">
      Attestation identifier
    </ResponseField>

    <ResponseField name="subject" type="string">
      Attested identity
    </ResponseField>

    <ResponseField name="issuer" type="string">
      Attestation issuer
    </ResponseField>

    <ResponseField name="schema" type="string">
      Attestation schema
    </ResponseField>

    <ResponseField name="data" type="object">
      Original attestation data
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of original creation
    </ResponseField>

    <ResponseField name="revokedAt" type="string">
      ISO 8601 timestamp of revocation
    </ResponseField>

    <ResponseField name="revocationReason" type="string">
      Reason for revocation
    </ResponseField>

    <ResponseField name="revocationDetails" type="string">
      Additional revocation details
    </ResponseField>

    <ResponseField name="publicReason" type="string">
      Public reason for revocation
    </ResponseField>

    <ResponseField name="status" type="string">
      Attestation status (revoked)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="impact" type="object">
  Impact of the revocation

  <Expandable title="impact properties">
    <ResponseField name="subjectNotified" type="boolean">
      Whether the subject was notified
    </ResponseField>

    <ResponseField name="trustScoreImpact" type="number">
      Impact on subject's trust score
    </ResponseField>

    <ResponseField name="relatedAttestations" type="number">
      Number of related attestations affected
    </ResponseField>

    <ResponseField name="publicVisibility" type="boolean">
      Whether revocation is publicly visible
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 timestamp of the response
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL (Basic Revocation) theme={null}
  curl -X DELETE "https://api.onzks.com/v1/trust/attestations/att_1234567890abcdef" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "reason": "relationship_ended",
      "details": "Business partnership has been terminated",
      "signature": "0xabcdef1234567890...",
      "notifySubject": true,
      "publicReason": "Partnership ended"
    }'
  ```

  ```bash cURL (Skill Outdated) theme={null}
  curl -X DELETE "https://api.onzks.com/v1/trust/attestations/att_abcdef1234567890" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "reason": "skill_outdated",
      "details": "Technology stack has changed significantly",
      "signature": "0x1234567890abcdef...",
      "notifySubject": true,
      "publicReason": "Technology outdated"
    }'
  ```

  ```bash cURL (Achievement Invalid) theme={null}
  curl -X DELETE "https://api.onzks.com/v1/trust/attestations/att_9876543210fedcba" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "reason": "achievement_invalid",
      "details": "Achievement was incorrectly awarded due to system error",
      "signature": "0x9876543210fedcba...",
      "notifySubject": true,
      "publicReason": "Incorrectly awarded"
    }'
  ```

  ```javascript JavaScript theme={null}
  async function revokeAttestation(attestationId, revocationData) {
    const {
      reason,
      details,
      signature,
      notifySubject = true,
      publicReason
    } = revocationData;

    const requestBody = {
      reason,
      details,
      signature,
      notifySubject,
      publicReason
    };

    const response = await fetch(
      `https://api.onzks.com/v1/trust/attestations/${attestationId}`,
      {
        method: 'DELETE',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(requestBody)
      }
    );

    const result = await response.json();

    if (result.success) {
      console.log(`✅ Attestation revoked: ${result.attestationId}`);
      console.log(`Reason: ${result.attestation.revocationReason}`);
      console.log(`Subject notified: ${result.impact.subjectNotified}`);
      console.log(`Trust score impact: ${result.impact.trustScoreImpact}`);
    } else {
      console.error('Failed to revoke attestation:', result.message);
    }

    return result;
  }

  // Usage examples
  await revokeAttestation('att_1234567890abcdef', {
    reason: 'relationship_ended',
    details: 'Business partnership has been terminated',
    signature: '0xabcdef1234567890...',
    notifySubject: true,
    publicReason: 'Partnership ended'
  });

  await revokeAttestation('att_abcdef1234567890', {
    reason: 'skill_outdated',
    details: 'Technology stack has changed significantly',
    signature: '0x1234567890abcdef...',
    notifySubject: true,
    publicReason: 'Technology outdated'
  });
  ```

  ```python Python theme={null}
  import requests
  import json

  def revoke_attestation(attestation_id, reason, details, signature, notify_subject=True, public_reason=None):
      request_body = {
          'reason': reason,
          'details': details,
          'signature': signature,
          'notifySubject': notify_subject
      }
      
      if public_reason:
          request_body['publicReason'] = public_reason
      
      response = requests.delete(
          f'https://api.onzks.com/v1/trust/attestations/{attestation_id}',
          headers={
              'Authorization': 'Bearer YOUR_API_KEY',
              'Content-Type': 'application/json'
          },
          json=request_body
      )
      
      result = response.json()
      
      if result['success']:
          print(f"✅ Attestation revoked: {result['attestationId']}")
          print(f"Reason: {result['attestation']['revocationReason']}")
          print(f"Subject notified: {result['impact']['subjectNotified']}")
          print(f"Trust score impact: {result['impact']['trustScoreImpact']}")
      else:
          print(f"Failed to revoke attestation: {result['message']}")
      
      return result

  # Usage examples
  revoke_attestation(
      'att_1234567890abcdef',
      'relationship_ended',
      'Business partnership has been terminated',
      '0xabcdef1234567890...',
      notify_subject=True,
      public_reason='Partnership ended'
  )

  revoke_attestation(
      'att_abcdef1234567890',
      'skill_outdated',
      'Technology stack has changed significantly',
      '0x1234567890abcdef...',
      notify_subject=True,
      public_reason='Technology outdated'
  )
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "success": true,
  "message": "Attestation revoked successfully",
  "attestationId": "att_1234567890abcdef",
  "attestation": {
    "id": "att_1234567890abcdef",
    "subject": "alice.zks",
    "issuer": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "schema": "relationship",
    "data": {
      "title": "Business Partner",
      "description": "Long-term business partnership",
      "category": "business",
      "value": "trusted",
      "metadata": {
        "relationshipType": "business_partner",
        "duration": "3 years",
        "projects": ["Joint Venture", "Consulting"]
      }
    },
    "createdAt": "2024-01-10T14:20:00Z",
    "revokedAt": "2024-01-20T15:45:00Z",
    "revocationReason": "relationship_ended",
    "revocationDetails": "Business partnership has been terminated",
    "publicReason": "Partnership ended",
    "status": "revoked"
  },
  "impact": {
    "subjectNotified": true,
    "trustScoreImpact": -5.2,
    "relatedAttestations": 2,
    "publicVisibility": true
  },
  "timestamp": "2024-01-20T15:45:00Z"
}
```

## Use Cases

### 1. Relationship Management

Revoke attestations when relationships end:

```javascript theme={null}
async function revokeRelationshipAttestation(attestationId, reason, details) {
  const revocationData = {
    reason: 'relationship_ended',
    details: details,
    signature: await signRevocation(attestationId, reason),
    notifySubject: true,
    publicReason: 'Relationship ended'
  };

  return await revokeAttestation(attestationId, revocationData);
}

// Usage
await revokeRelationshipAttestation(
  'att_1234567890abcdef',
  'Business partnership has been terminated'
);
```

### 2. Skill Updates

Revoke outdated skill attestations:

```javascript theme={null}
async function revokeOutdatedSkill(attestationId, newTechnology) {
  const revocationData = {
    reason: 'skill_outdated',
    details: `Technology stack has changed to ${newTechnology}`,
    signature: await signRevocation(attestationId, 'skill_outdated'),
    notifySubject: true,
    publicReason: 'Technology outdated'
  };

  return await revokeAttestation(attestationId, revocationData);
}

// Usage
await revokeOutdatedSkill('att_abcdef1234567890', 'React 18');
```

### 3. Achievement Corrections

Revoke incorrectly awarded achievements:

```javascript theme={null}
async function revokeIncorrectAchievement(attestationId, correction) {
  const revocationData = {
    reason: 'achievement_invalid',
    details: `Achievement was incorrectly awarded: ${correction}`,
    signature: await signRevocation(attestationId, 'achievement_invalid'),
    notifySubject: true,
    publicReason: 'Incorrectly awarded'
  };

  return await revokeAttestation(attestationId, revocationData);
}

// Usage
await revokeIncorrectAchievement(
  'att_9876543210fedcba',
  'System error caused incorrect achievement award'
);
```

### 4. Batch Revocation

Revoke multiple attestations at once:

```javascript theme={null}
async function revokeMultipleAttestations(attestationIds, reason, details) {
  const results = [];
  
  for (const attestationId of attestationIds) {
    try {
      const result = await revokeAttestation(attestationId, {
        reason,
        details,
        signature: await signRevocation(attestationId, reason),
        notifySubject: true
      });
      results.push({ attestationId, success: true, result });
    } catch (error) {
      results.push({ attestationId, success: false, error: error.message });
    }
  }
  
  const successful = results.filter(r => r.success);
  const failed = results.filter(r => !r.success);
  
  console.log(`Successfully revoked ${successful.length} attestations`);
  if (failed.length > 0) {
    console.log(`Failed to revoke ${failed.length} attestations`);
  }
  
  return results;
}
```

### 5. Revocation Analytics

Analyze revocation patterns:

```javascript theme={null}
function analyzeRevocations(revokedAttestations) {
  const analysis = {
    byReason: groupBy(revokedAttestations, 'revocationReason'),
    bySchema: groupBy(revokedAttestations, 'schema'),
    byTimeframe: groupByTimeframe(revokedAttestations),
    averageImpact: calculateAverageImpact(revokedAttestations),
    trends: identifyRevocationTrends(revokedAttestations)
  };
  
  return analysis;
}

function groupBy(array, key) {
  return array.reduce((groups, item) => {
    const value = item[key];
    if (!groups[value]) {
      groups[value] = [];
    }
    groups[value].push(item);
    return groups;
  }, {});
}
```

## Best Practices

### 1. Signature Verification

Always verify signatures before revoking:

```javascript theme={null}
async function verifyRevocationSignature(attestationId, reason, signature) {
  const message = JSON.stringify({
    attestationId,
    reason,
    timestamp: Date.now()
  });
  
  const recoveredAddress = await recoverAddress(message, signature);
  return recoveredAddress === attestation.issuer;
}
```

### 2. Impact Assessment

Assess the impact before revoking:

```javascript theme={null}
async function assessRevocationImpact(attestationId) {
  const attestation = await getAttestation(attestationId);
  
  const impact = {
    trustScoreImpact: calculateTrustScoreImpact(attestation),
    relatedAttestations: await findRelatedAttestations(attestation),
    subjectImpact: await assessSubjectImpact(attestation.subject),
    publicImpact: assessPublicImpact(attestation)
  };
  
  return impact;
}
```

### 3. Notification Management

Handle notifications appropriately:

```javascript theme={null}
function shouldNotifySubject(attestation, reason) {
  const notificationReasons = [
    'relationship_ended',
    'skill_outdated',
    'achievement_invalid'
  ];
  
  return notificationReasons.includes(reason) && attestation.public;
}
```

### 4. Audit Trail

Maintain audit trail for revocations:

```javascript theme={null}
function createRevocationAudit(attestation, revocationData) {
  return {
    attestationId: attestation.id,
    subject: attestation.subject,
    issuer: attestation.issuer,
    originalData: attestation.data,
    revocationReason: revocationData.reason,
    revocationDetails: revocationData.details,
    revokedAt: new Date().toISOString(),
    revokedBy: revocationData.issuer,
    signature: revocationData.signature
  };
}
```

## Related Endpoints

* [Get Attestations](/api-reference/trust-layer/get-attestations) - Retrieve attestations
* [Create Attestation](/api-reference/trust-layer/create-attestation) - Create new attestations
* [Evaluate Policy](/api-reference/trust-layer/evaluate-policy) - Evaluate trust policies
* [Get Modules](/api-reference/trust-layer/get-modules) - Get available trust modules

## Troubleshooting

### "Attestation not found"

**Cause**: Invalid attestation ID or attestation doesn't exist.

**Solution**:

* Verify the attestation ID is correct
* Check if the attestation exists
* Ensure you have access to the attestation

### "Not authorized to revoke"

**Cause**: You are not the issuer of the attestation.

**Solution**:

* Only the original issuer can revoke an attestation
* Verify you are using the correct account
* Check the attestation issuer

### "Attestation already revoked"

**Cause**: The attestation has already been revoked.

**Solution**:

* Check the attestation status
* You cannot revoke an already revoked attestation
* Consider the impact of the previous revocation

### "Invalid signature"

**Cause**: The signature doesn't match the revocation data.

**Solution**:

* Verify the signature is correctly generated
* Ensure the message being signed matches the revocation data
* Check that the correct private key is being used

## Rate Limits

Attestation revocation requests are subject to rate limits:

* **Free tier**: 10 revocations per minute
* **Starter tier**: 50 revocations per minute
* **Professional tier**: 200 revocations per minute
* **Enterprise tier**: Custom limits

Implement queuing for batch revocations to avoid rate limits.