Revoke Attestation

curl --request DELETE \
  --url https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "<string>",
  "details": "<string>",
  "signature": "<string>",
  "notifySubject": true,
  "publicReason": "<string>"
}
'

import requests

url = "https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId"

payload = {
    "reason": "<string>",
    "details": "<string>",
    "signature": "<string>",
    "notifySubject": True,
    "publicReason": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.delete(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'DELETE',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    reason: '<string>',
    details: '<string>',
    signature: '<string>',
    notifySubject: true,
    publicReason: '<string>'
  })
};

fetch('https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => '<string>',
    'details' => '<string>',
    'signature' => '<string>',
    'notifySubject' => true,
    'publicReason' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId"

	payload := strings.NewReader("{\n  \"reason\": \"<string>\",\n  \"details\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"notifySubject\": true,\n  \"publicReason\": \"<string>\"\n}")

	req, _ := http.NewRequest("DELETE", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.delete("https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"<string>\",\n  \"details\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"notifySubject\": true,\n  \"publicReason\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"<string>\",\n  \"details\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"notifySubject\": true,\n  \"publicReason\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "attestationId": "<string>",
  "attestation": {
    "id": "<string>",
    "subject": "<string>",
    "issuer": "<string>",
    "schema": "<string>",
    "data": {},
    "createdAt": "<string>",
    "revokedAt": "<string>",
    "revocationReason": "<string>",
    "revocationDetails": "<string>",
    "publicReason": "<string>",
    "status": "<string>"
  },
  "impact": {
    "subjectNotified": true,
    "trustScoreImpact": 123,
    "relatedAttestations": 123,
    "publicVisibility": true
  },
  "timestamp": "<string>"
}

DELETE

trust

attestations

:attestationId

Revoke Attestation

curl --request DELETE \
  --url https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "<string>",
  "details": "<string>",
  "signature": "<string>",
  "notifySubject": true,
  "publicReason": "<string>"
}
'

import requests

url = "https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId"

payload = {
    "reason": "<string>",
    "details": "<string>",
    "signature": "<string>",
    "notifySubject": True,
    "publicReason": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.delete(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'DELETE',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    reason: '<string>',
    details: '<string>',
    signature: '<string>',
    notifySubject: true,
    publicReason: '<string>'
  })
};

fetch('https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => '<string>',
    'details' => '<string>',
    'signature' => '<string>',
    'notifySubject' => true,
    'publicReason' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId"

	payload := strings.NewReader("{\n  \"reason\": \"<string>\",\n  \"details\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"notifySubject\": true,\n  \"publicReason\": \"<string>\"\n}")

	req, _ := http.NewRequest("DELETE", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.delete("https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"<string>\",\n  \"details\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"notifySubject\": true,\n  \"publicReason\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-mainnet.onzks.com/v1/trust/attestations/:attestationId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"<string>\",\n  \"details\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"notifySubject\": true,\n  \"publicReason\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "<string>",
  "attestationId": "<string>",
  "attestation": {
    "id": "<string>",
    "subject": "<string>",
    "issuer": "<string>",
    "schema": "<string>",
    "data": {},
    "createdAt": "<string>",
    "revokedAt": "<string>",
    "revocationReason": "<string>",
    "revocationDetails": "<string>",
    "publicReason": "<string>",
    "status": "<string>"
  },
  "impact": {
    "subjectNotified": true,
    "trustScoreImpact": 123,
    "relatedAttestations": 123,
    "publicVisibility": true
  },
  "timestamp": "<string>"
}

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.

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.

Parameters

string

required

Unique identifier of the attestation to revoke

Request Body

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)

string

Additional details about the revocation reason

string

required

Cryptographic signature proving ownership of the attestation

boolean

Whether to notify the subject about the revocation (default: true)

string

Public reason for the revocation (visible to others)

Response

boolean

Indicates if the attestation was revoked successfully

string

Success message

string

Identifier of the revoked attestation

object

Revoked attestation details

Show attestation properties

string

Attestation identifier

string

Attested identity

string

Attestation issuer

string

Attestation schema

object

Original attestation data

string

ISO 8601 timestamp of original creation

string

ISO 8601 timestamp of revocation

string

Reason for revocation

string

Additional revocation details

string

Public reason for revocation

string

Attestation status (revoked)

object

Impact of the revocation

Show impact properties

boolean

Whether the subject was notified

number

Impact on subject’s trust score

Number of related attestations affected

boolean

Whether revocation is publicly visible

string

ISO 8601 timestamp of the response

Examples

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"
  }'

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"
  }'

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"
  }'

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'
});

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'
)

Response Example

{
  "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:

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:

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:

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:

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:

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:

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:

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:

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:

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
  };
}

Get Attestations - Retrieve attestations
Create Attestation - Create new attestations
Evaluate Policy - Evaluate trust policies
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.

API Documentation

Identity

Scores

Achievements

Trading

Trust Layer

Developer Tools

Revoke Attestation

Overview

Parameters

Request Body

Response

Examples

Response Example

Use Cases

1. Relationship Management

2. Skill Updates

3. Achievement Corrections

4. Batch Revocation

5. Revocation Analytics

Best Practices

1. Signature Verification

2. Impact Assessment

3. Notification Management

4. Audit Trail

Troubleshooting

”Attestation not found”

”Not authorized to revoke”

”Attestation already revoked”

”Invalid signature”

Rate Limits

​Overview

​Parameters

​Request Body

​Response

​Examples

​Response Example

​Use Cases

​1. Relationship Management

​2. Skill Updates

​3. Achievement Corrections

​4. Batch Revocation

​5. Revocation Analytics

​Best Practices

​1. Signature Verification

​2. Impact Assessment

​3. Notification Management

​4. Audit Trail

​Related Endpoints

​Troubleshooting

​”Attestation not found”

​”Not authorized to revoke”

​”Attestation already revoked”

​”Invalid signature”

​Rate Limits

Overview

Parameters

Request Body

Response

Examples

Response Example

Use Cases

1. Relationship Management

2. Skill Updates

3. Achievement Corrections

4. Batch Revocation

5. Revocation Analytics

Best Practices

1. Signature Verification

2. Impact Assessment

3. Notification Management

4. Audit Trail

Related Endpoints

Troubleshooting

”Attestation not found”

”Not authorized to revoke”

”Attestation already revoked”

”Invalid signature”

Rate Limits