Attestation API Reference

Complete API reference for Phala Cloud’s remote attestation service. Covers all endpoints, parameters, schemas, and integration patterns for Intel SGX and TDX quote verification.

Looking to get started quickly? Check out our 5-minute quickstart guide first.

API Endpoints

POST /attestations/verify

Upload and verify an SGX or TDX attestation quote.

Supported Input Formats:

1. File Upload (multipart/form-data) - Recommended for most use cases
2. Hex String JSON (application/json) - For programmatic integration
3. Hex String Form Data (application/x-www-form-urlencoded) - For simple form submissions

Quote Requirements:

• Valid Intel SGX DCAP or TDX quote (2-8KB typical size)
• Complete certificate chains included
• ECDSA-P256 signature format
• Generated from genuine Intel SGX/TDX platform

Request Parameters:

Parameter	Type	Format	Description
file	binary	multipart/form-data	Quote file upload (recommended)
hex	string	JSON or form data	Hex-encoded quote data

Hex String Notes:

• Optional 0x prefix supported
• Case insensitive
• Whitespace automatically trimmed

File Upload

curl -X POST "https://cloud-api.phala.com/api/v1/attestations/verify" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@quote.bin"

curl -X POST "https://cloud-api.phala.com/api/v1/attestations/verify" \
  -H "Content-Type: application/json" \
  -d '{"hex": "0x48656c6c6f..."}'

curl -X POST "https://cloud-api.phala.com/api/v1/attestations/verify" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "hex=48656c6c6f..."

// File upload
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://cloud-api.phala.com/api/v1/attestations/verify', {
  method: 'POST',
  body: formData
});

const result = await response.json();
console.log('Verified:', result.quote.verified);
console.log('Checksum:', result.checksum);

import requests

# File upload
with open('quote.bin', 'rb') as f:
    response = requests.post(
        'https://cloud-api.phala.com/api/v1/attestations/verify',
        files={'file': f}
    )

result = response.json()
print(f"Verified: {result['quote']['verified']}")
print(f"Checksum: {result['checksum']}")

Response Schema: VerificationResponse

{
  "success": true,
  "quote": {
    "header": {
      "version": 4,
      "ak_type": "ECDSA_P256", 
      "tee_type": "TEE_TDX",
      "qe_vendor": "0x939a7233f79c4ca9940a0db3957f0607",
      "user_data": "0x65004f4410967df7fc6a1faf0d9b6fc000000000"
    },
    "body": {
      "tee_tcb_svn": "06010300000000000000000000000000",
      "mrseam": "0x5b38e33a6487958b72c3c12a938eaa5e3fd4510c51aeeab58c7d5ecee41d7c436489d6c8e4f92f160b7cad34207b00c1",
      "mrtd": "0xc68518a0ebb42136c12b2275164f8c72f25fa9a34392228687ed6e9caeb9c0f1dbd895e9cf475121c029dc47e70e91fd",
      "rtmr0": "0x0bb3d6375f94482cdd24b767e4a0d720348527c4f2ab433d77f842b9394fa1638bb6df83fb0a1301f29c71bf60da48bb",
      "rtmr1": "0x154e08f5c1f7b1fce4cbfe1c14f3ba67b70044ede2751487279cd1f2e4239dee99a6d45e24ebde6b6a6f5ae49878e0e6",
      "rtmr2": "0x9edcd363660e85b71c318324996dda756c372d9f6960edbfa863b1e684822eb48dd95e218ae2b78e51ef97f3b8f5c9dc",
      "rtmr3": "0x56491496510e698faad85d0dc444636174789195f272899ab5b1fc8f83531375fb9077cb32e7dac16667470f854ba5d0",
      "reportdata": "0x00000000000000000000000000000000000000000000000000000000000000006ab141daaabe33787711861c8aa66ad3c95c49cebfd9525c85911b90233408ed"
    },
    "cert_data": "-----BEGIN CERTIFICATE-----\nMIIE8TCCBJegAwIBAgIVANOAucofjgQfe1LTb4vrnuUCYTTrMAoGCCqGSM49BAMC...",
    "verified": true
  },
  "checksum": "9aa049fb9049d4f582ca316206f7cf34ee185c2b5b63370a518921432385b81a",
  "can_download": true,
  "uploaded_at": "2025-08-15T16:01:28+00:00",
  "quote_collateral": {
    "pck_crl_issuer_chain": "-----BEGIN CERTIFICATE-----...",
    "tcb_info": "{\"id\":\"TDX\",\"version\":3,...}",
    "qe_identity": "{\"id\":\"TD_QE\",\"version\":2,...}"
  }
}

Response Fields:

Field	Type	Description
success	boolean	Whether verification process completed successfully
quote	Quote	Parsed quote object with header, body, and verification status
checksum	string	SHA256 hash serving as unique identifier for this quote
can_download	boolean	Whether the raw binary quote data can be downloaded
uploaded_at	string	ISO 8601 timestamp when quote was first uploaded to Phala Cloud
quote_collateral	QuoteCollateralV3	Cryptographic verification data from Intel PCS

Error Responses:

Error Responses:

Status	Cause	Common Issues
400	Input validation	Missing data, both file and hex provided, invalid hex format
422	Invalid quote	Wrong file type, corrupted data, missing certificates
400	Verification failed	Non-genuine platform, revoked certificates, outdated TCB
500	Server error	Service unavailable, Intel PCS issues

---

GET /attestations/view/

Retrieve complete quote details including header, body, and verification status.

Path Parameters:

• checksum (string): Quote’s unique SHA256 identifier

cURL

curl "https://cloud-api.phala.com/api/v1/attestations/view/{checksum}"

const response = await fetch(`https://cloud-api.phala.com/api/v1/attestations/view/${checksum}`);
const quote = await response.json();
console.log('TEE Type:', quote.header.tee_type);
console.log('MRTD:', quote.body.mrtd);
console.log('Verified:', quote.verified);

response = requests.get(f'https://cloud-api.phala.com/api/v1/attestations/view/{checksum}')
quote = response.json()
print(f"TEE Type: {quote['header']['tee_type']}")
print(f"MRTD: {quote['body']['mrtd']}")
print(f"Verified: {quote['verified']}")
print(f"Uploaded: {quote['uploaded_at']}")

Response: Full Quote object with additional metadata

{
  "header": {
    "version": 4,
    "ak_type": "ECDSA_P256",
    "tee_type": "TEE_TDX",
    "qe_vendor": "0x939a7233f79c4ca9940a0db3957f0607",
    "user_data": "0x65004f4410967df7fc6a1faf0d9b6fc000000000"
  },
  "body": {
    "tee_tcb_svn": "06010300000000000000000000000000",
    "mrtd": "0xc68518a0ebb42136c12b2275164f8c72f25fa9a34392228687ed6e9caeb9c0f1dbd895e9cf475121c029dc47e70e91fd",
    "rtmr0": "0x0bb3d6375f94482cdd24b767e4a0d720348527c4f2ab433d77f842b9394fa1638bb6df83fb0a1301f29c71bf60da48bb",
    "rtmr1": "0x154e08f5c1f7b1fce4cbfe1c14f3ba67b70044ede2751487279cd1f2e4239dee99a6d45e24ebde6b6a6f5ae49878e0e6",
    "reportdata": "0x00000000000000000000000000000000000000000000000000000000000000001d7ce0146d345b6e3e28b5605db5bbd7502507092f8f1e8f48c5e8f2d0e750f3"
  },
  "cert_data": "-----BEGIN CERTIFICATE-----\\nMIIE8TCCBJegAwIBAgIVANOAucofjgQfe1LTb4vrnuUCYTTrMAoGCCqGSM49BAMC\\nMHAxIjAgBgNVBAMMGUludGVsIFNHWCBQQ0sgUGxhdGZvcm0gQ0ExGjAYBgNVBAoM\\nEUludGVsIENvcnBvcmF0aW9uMRQwEgYDVQQHDAtTYW50YSBDbGFyYTELMAkGA1UE\\nCAwCQ0ExCzAJBgNVBAYTAlVTMB4XDTI1MDEwNDAxMDQwNloXDTMyMDEwNDAxMDQw\\nNlowcDEiMCAGA1UEAwwZSW50ZWwgU0dYIFBDSyBDZXJ0aWZpY2F0ZTEaMBgGA1UE\\n...",
  "verified": true,
  "uploaded_at": "2025-08-15T16:01:28+00:00",
  "checksum": "9540fda5e6416c9d02bae726b146be58bee3caccfe7f874dbc68c808a13b1139",
  "can_download": true
}

Error Responses:

• 404 Not Found: Quote with specified checksum doesn’t exist

---

GET /attestations/collateral/

Get cryptographic collateral (certificates, CRLs, TCB info) used for verification.

Response Headers:

• Cache-Control: public, max-age=86400 (24 hour cache)
• ETag: "{checksum}" (for conditional requests)

cURL

curl "https://cloud-api.phala.com/api/v1/attestations/collateral/{checksum}"

const response = await fetch(`https://cloud-api.phala.com/api/v1/attestations/collateral/${checksum}`);
const collateral = await response.json();

// Parse nested JSON fields
const tcbInfo = JSON.parse(collateral.tcb_info);
const qeIdentity = JSON.parse(collateral.qe_identity);

console.log('Platform FMSPC:', tcbInfo.fmspc);
console.log('TCB Issue Date:', tcbInfo.issueDate);
console.log('QE Identity Version:', qeIdentity.version);

import json
response = requests.get(f'https://cloud-api.phala.com/api/v1/attestations/collateral/{checksum}')
collateral = response.json()
tcb_info = json.loads(collateral['tcb_info'])
qe_identity = json.loads(collateral['qe_identity'])

print(f"Platform FMSPC: {tcb_info['fmspc']}")
print(f"TCB Issue Date: {tcb_info['issueDate']}")
print(f"QE Identity Version: {qe_identity['version']}")

Response: QuoteCollateralV3 object

Headers:

• Cache-Control: public, max-age=86400
• CDN-Cache-Control: public, max-age=86400
• Vary: Accept-Encoding
• ETag: "9540fda5e6416c9d02bae726b146be58bee3caccfe7f874dbc68c808a13b1139"

Error Responses:

• 404 Not Found: Quote with specified checksum doesn’t exist
• 400 Bad Request: Unable to retrieve collateral data

---

GET /attestations/raw/

Download original binary quote data.

Response:

• Content-Type: application/octet-stream
• Content-Disposition: attachment; filename={checksum}.bin
• Content-Length: {size} (typically 2-8KB)

cURL

curl "https://cloud-api.phala.com/api/v1/attestations/raw/{checksum}" \
  --output quote.bin

const response = await fetch(`https://cloud-api.phala.com/api/v1/attestations/raw/${checksum}`);
const blob = await response.blob();

response = requests.get(f'https://cloud-api.phala.com/api/v1/attestations/raw/{checksum}')
with open(f'{checksum}.bin', 'wb') as f:
    f.write(response.content)
print(f'Downloaded {len(response.content)} bytes')

---

HEAD /attestations/raw/

Check quote existence and size without downloading.

cURL

curl -I "https://cloud-api.phala.com/api/v1/attestations/raw/{checksum}"

const response = await fetch(
  `https://cloud-api.phala.com/api/v1/attestations/raw/${checksum}`,
  { method: 'HEAD' }
);
const size = response.headers.get('Content-Length');
console.log(`Quote size: ${size} bytes`);

response = requests.head(f'https://cloud-api.phala.com/api/v1/attestations/raw/{checksum}')
size = response.headers.get('Content-Length')
print(f'Quote size: {size} bytes')

---

GET /attestations/recent

List recently uploaded quotes with pagination.

Query Parameters:

• skip (integer): Records to skip (default: 0)
• limit (integer): Maximum records to return (default: 20)

cURL

curl "https://cloud-api.phala.com/api/v1/attestations/recent?limit=10"

const response = await fetch('https://cloud-api.phala.com/api/v1/attestations/recent?limit=10');
const quotes = await response.json();
quotes.forEach(q => console.log(`${q.checksum}: ${q.verified ? 'verified' : 'failed'}`));

response = requests.get('https://cloud-api.phala.com/api/v1/attestations/recent', 
                       params={'limit': 10})
for quote in response.json():
    status = 'verified' if quote['verified'] else 'failed'
    print(f"{quote['checksum']}: {status}")

Returns array of quote summaries:

[
  {
    "checksum": "9540fda5e6416c9d02bae726b146be58bee3caccfe7f874dbc68c808a13b1139",
    "verified": 1,
    "created_at": "2025-08-15T16:01:28+00:00"
  }
]

Field	Type	Description
checksum	string	SHA256 hash (unique identifier)
verified	integer	1 = verified, 0 = failed
created_at	string	Upload timestamp (ISO 8601)

---

Data Models

Quote

{
  "header": QuoteHeader,
  "body": QuoteBody,
  "cert_data": string | null,
  "verified": boolean
}

QuoteHeader

{
  "version": 4,
  "ak_type": "ECDSA_P256",
  "tee_type": "TEE_TDX",
  "qe_vendor": "0x939a7233f79c4ca9940a0db3957f0607",
  "user_data": "0x65004f4410967df7fc6a1faf0d9b6fc000000000"
}

Field	Type	Description
version	integer	Quote format version (typically 4)
ak_type	string	Attestation key type (“ECDSA_P256”)
tee_type	string	”TEE_SGX” or “TEE_TDX”
qe_vendor	string	Quoting Enclave vendor ID (hex)
user_data	string	User-defined data (hex, 20 bytes)

QuoteBody

Core attestation measurements and platform data.

Complete Sample Data

{
  "tee_tcb_svn": "06010300000000000000000000000000",
  "mrseam": "0x5b38e33a6487958b72c3c12a938eaa5e3fd4510c51aeeab58c7d5ecee41d7c436489d6c8e4f92f160b7cad34207b00c1",
  "mrsignerseam": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "seamattributes": "0x0000000000000000",
  "tdattributes": "0x0000001000000000",
  "xfam": "0xe702060000000000",
  "mrtd": "0xc68518a0ebb42136c12b2275164f8c72f25fa9a34392228687ed6e9caeb9c0f1dbd895e9cf475121c029dc47e70e91fd",
  "mrconfig": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "mrowner": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "mrownerconfig": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "rtmr0": "0x0bb3d6375f94482cdd24b767e4a0d720348527c4f2ab433d77f842b9394fa1638bb6df83fb0a1301f29c71bf60da48bb",
  "rtmr1": "0x154e08f5c1f7b1fce4cbfe1c14f3ba67b70044ede2751487279cd1f2e4239dee99a6d45e24ebde6b6a6f5ae49878e0e6",
  "rtmr2": "0x9edcd363660e85b71c318324996dda756c372d9f6960edbfa863b1e684822eb48dd95e218ae2b78e51ef97f3b8f5c9dc",
  "rtmr3": "0x6485726f70094502412a81dc0097b3bd67181f6eb8c647fe6ddb47c8efa38e6f35b88bd99a4ece93c9f3d44be45c58a0",
  "reportdata": "0x00000000000000000000000000000000000000000000000000000000000000001d7ce0146d345b6e3e28b5605db5bbd7502507092f8f1e8f48c5e8f2d0e750f3"
}

Complete Field Reference:

Field	Type	Description	Size
tee_tcb_svn	string	TCB Security Version Number (platform firmware version)	16 bytes
mrseam	string	Measurement of SEAM module (Intel TDX hypervisor component)	SHA384
mrsignerseam	string	SEAM signer measurement (hash of entity that signed SEAM)	SHA384
seamattributes	string	SEAM module attributes and capabilities	8 bytes
tdattributes	string	Trust Domain attributes and configuration flags	8 bytes
xfam	string	Extended Features Available Mask (CPU features accessible to TD)	8 bytes
mrtd	string	Measurement Root of Trust Domain (TD fingerprint/initial state)	SHA384
mrconfig	string	Configuration measurement	SHA384
mrowner	string	TD owner measurement	SHA384
mrownerconfig	string	Owner configuration measurement	SHA384
rtmr0	string	Runtime Measurement Register 0 (virtual hardware environment)	SHA384
rtmr1	string	Runtime Measurement Register 1 (Linux kernel)	SHA384
rtmr2	string	Runtime Measurement Register 2 (kernel cmdline and initrd)	SHA384
rtmr3	string	Runtime Measurement Register 3 (application-specific measurements)	SHA384
reportdata	string	User-defined data (nonces, challenges, application state)	64 bytes

Critical Fields for Verification:

• mrtd: Trust domain fingerprint - must match expected value
• rtmr0-3: Software measurements - verify boot chain and application integrity
• reportdata: Challenge-response data - must contain expected nonce/response
• tee_tcb_svn: Platform security level - check against known vulnerabilities

QuoteCollateralV3

Cryptographic verification data from Intel PCS.

Sample Data

{
  "pck_crl_issuer_chain": "-----BEGIN CERTIFICATE-----...",
  "root_ca_crl": "deadbeef1234...",
  "pck_crl": "cafebabe5678...",
  "tcb_info_issuer_chain": "-----BEGIN CERTIFICATE-----...",
  "tcb_info": "{\"version\":3,\"issueDate\":\"2025-01-01T00:00:00Z\",...}",
  "tcb_info_signature": "3045022100abc123...",
  "qe_identity_issuer_chain": "-----BEGIN CERTIFICATE-----...",
  "qe_identity": "{\"version\":2,\"issueDate\":\"2025-01-01T00:00:00Z\",...}",
  "qe_identity_signature": "3046022100def456..."
}

Complete Field Reference:

Field	Type	Description
pck_crl_issuer_chain	string	PEM certificate chain for PCK Certificate Revocation List verification
root_ca_crl	string	Root CA Certificate Revocation List (hex-encoded, optional)
pck_crl	string	Platform Certification Key Certificate Revocation List (hex-encoded)
tcb_info_issuer_chain	string	PEM certificate chain for TCB info signature verification
tcb_info	string	JSON string containing Trusted Computing Base information and security levels
tcb_info_signature	string	ECDSA signature over the TCB info data (hex-encoded)
qe_identity_issuer_chain	string	PEM certificate chain for Quoting Enclave identity verification
qe_identity	string	JSON string containing QE identity, version, and TCB levels
qe_identity_signature	string	ECDSA signature over the QE identity data (hex-encoded)

Usage Notes:

• Certificate Chains: Used to validate signatures back to Intel root certificates
• CRL Data: Check for revoked certificates and compromised platforms
• TCB Info: Contains platform security version info and vulnerability advisories
• QE Identity: Validates the Quoting Enclave that signed the quote
• Signatures: All signatures use ECDSA-P256 and must be validated against certificate chains

Verification Process

1. Parse - Extract header, body, and certificates from binary quote
2. Platform Check - Verify quote from genuine Intel SGX/TDX platform
3. TCB Validation - Check platform firmware is current and not revoked
4. Signature Verification - Validate using Intel-provided certificates
5. Storage - Cache results and collateral for future access

Integration Patterns

Basic Verification Workflow

Binary File Upload:

# 1. Upload quote file
checksum=$(curl -s -X POST "$API_BASE/verify" -F "file=@quote.bin" | jq -r .checksum)

# 2. Check verification status
curl "$API_BASE/view/$checksum" | jq .verified

# 3. Share results
echo "Verification report: https://proof.t16z.com/reports/$checksum"

Hex Data from dstack SDK:

import crypto from 'crypto';

// 1. Generate and upload quote
const client = new DstackClient(endpoint);
// Manually hash data if > 64 bytes
const data = 'challenge';
const hash = crypto.createHash('sha256').update(data).digest();
const quoteResult = await client.getQuote(hash.slice(0, 32));
const response = await fetch('$API_BASE/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ hex: quoteResult.quote })
});
const { checksum, quote: result } = await response.json();

// 2. Verification status
console.log('Verified:', result.verified);
console.log('Report:', `https://proof.t16z.com/reports/${checksum}`);

Hex String Conversion:

# Convert hex file to binary
xxd -r -p quote.hex > quote.bin

# Or send hex directly
curl -X POST "$API_BASE/verify" \
  -H "Content-Type: application/json" \
  -d "{\"hex\": \"$(cat quote.hex | tr -d '\n')\"}"

Error Handling Best Practices

Input Format Issues:

• 422 Unprocessable Entity: Wrong file format, corrupted data, or invalid hex
• 400 Bad Request: Missing input, invalid hex characters, or format conflicts

Verification Issues:

• 400 Verification Failed: Platform may be development/non-genuine
• 404 Not Found: Invalid checksum or quote not uploaded
• 500 Server Error: Retry after delay, Intel PCS may be unavailable

Cache Policy

• Quote collateral is cached for 24 hours to improve performance
• Raw quote data and verification results are stored permanently
• ETags are provided for efficient client-side caching

Security Notes

• All quotes are publicly accessible by checksum
• Always validate reportdata contains expected nonces/challenges
• Check verified: true before trusting quote contents
• Verification depends on Intel’s Provisioning Certification Service

---

Need help getting started? Check out our quick start guide for a 5-minute walkthrough.