API Documentation

Authentication

The Attestiv API uses JWT (JSON Web Tokens) for authentication. Include the token in the Authorization header for all authenticated requests.

POST /auth/token/

Obtain an access token using your credentials.

curl -X POST https://attestiv.io/api/v1/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

import requests

response = requests.post(
    "https://attestiv.io/api/v1/auth/token/",
    json={
        "username": "your_username",
        "password": "your_password"
    }
)

tokens = response.json()
access_token = tokens["access"]
refresh_token = tokens["refresh"]

const response = await fetch("https://attestiv.io/api/v1/auth/token/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "your_username",
    password: "your_password"
  })
});

const { access, refresh } = await response.json();

Response

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Using the token: Include the access token in the Authorization header for authenticated requests: Authorization: Bearer YOUR_ACCESS_TOKEN

POST /auth/token/refresh/

Refresh an expired access token.

curl -X POST https://attestiv.io/api/v1/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "YOUR_REFRESH_TOKEN"}'

response = requests.post(
    "https://attestiv.io/api/v1/auth/token/refresh/",
    json={"refresh": refresh_token}
)
new_access_token = response.json()["access"]

const response = await fetch("https://attestiv.io/api/v1/auth/token/refresh/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ refresh: refreshToken })
});
const { access } = await response.json();

Vendors

Manage vendor accounts, signing keys, and domain verification.

POST /vendors/register/ Public

Register a new vendor account.

curl -X POST https://attestiv.io/api/v1/vendors/register/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "acme_corp",
    "email": "admin@acme.com",
    "password": "secure_password_123",
    "name": "Acme Corporation",
    "domain": "acme.com"
  }'

response = requests.post(
    "https://attestiv.io/api/v1/vendors/register/",
    json={
        "username": "acme_corp",
        "email": "admin@acme.com",
        "password": "secure_password_123",
        "name": "Acme Corporation",
        "domain": "acme.com"
    }
)
vendor = response.json()

const response = await fetch("https://attestiv.io/api/v1/vendors/register/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "acme_corp",
    email: "admin@acme.com",
    password: "secure_password_123",
    name: "Acme Corporation",
    domain: "acme.com"
  })
});
const vendor = await response.json();

Response

{
  "id": "vnd_abc123",
  "name": "Acme Corporation",
  "domain": "acme.com",
  "is_domain_verified": false,
  "created_at": "2026-01-20T10:00:00Z",
  "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

GET PUT /vendors/me/ Auth Required

Get or update your vendor profile.

# Get profile
curl https://attestiv.io/api/v1/vendors/me/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Update profile
curl -X PUT https://attestiv.io/api/v1/vendors/me/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp Inc."}'

headers = {"Authorization": f"Bearer {access_token}"}

# Get profile
response = requests.get(
    "https://attestiv.io/api/v1/vendors/me/",
    headers=headers
)
profile = response.json()

# Update profile
response = requests.put(
    "https://attestiv.io/api/v1/vendors/me/",
    headers=headers,
    json={"name": "Acme Corp Inc."}
)

const headers = { "Authorization": `Bearer ${accessToken}` };

// Get profile
const profile = await fetch("https://attestiv.io/api/v1/vendors/me/", {
  headers
}).then(r => r.json());

// Update profile
await fetch("https://attestiv.io/api/v1/vendors/me/", {
  method: "PUT",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Acme Corp Inc." })
});

POST /vendors/keys/ Auth Required

Create a new Ed25519 signing key for invoice signatures.

# Create a new signing key
curl -X POST https://attestiv.io/api/v1/vendors/keys/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key 2026"}'

# List all keys
curl https://attestiv.io/api/v1/vendors/keys/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Revoke a key
curl -X POST https://attestiv.io/api/v1/vendors/keys/KEY_ID/revoke/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

headers = {"Authorization": f"Bearer {access_token}"}

# Create a new signing key
response = requests.post(
    "https://attestiv.io/api/v1/vendors/keys/",
    headers=headers,
    json={"name": "Production Key 2026"}
)
key = response.json()
# IMPORTANT: Save private_key securely - shown only once!
private_key = key["private_key"]

# List all keys
keys = requests.get(
    "https://attestiv.io/api/v1/vendors/keys/",
    headers=headers
).json()

# Revoke a key
requests.post(
    f"https://attestiv.io/api/v1/vendors/keys/{key_id}/revoke/",
    headers=headers
)

const headers = {
  "Authorization": `Bearer ${accessToken}`,
  "Content-Type": "application/json"
};

// Create a new signing key
const key = await fetch("https://attestiv.io/api/v1/vendors/keys/", {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "Production Key 2026" })
}).then(r => r.json());
// IMPORTANT: Save privateKey securely - shown only once!
const privateKey = key.private_key;

// List all keys
const keys = await fetch("https://attestiv.io/api/v1/vendors/keys/", {
  headers
}).then(r => r.json());

// Revoke a key
await fetch(`https://attestiv.io/api/v1/vendors/keys/${keyId}/revoke/`, {
  method: "POST",
  headers
});

Response (Create Key)

{
  "id": "sk_xyz789",
  "name": "Production Key 2026",
  "public_key": "ed25519:MC4CAQAwBQYDK2VwBCIEI...",
  "private_key": "ed25519:MFECAQEwBQYDK2VwBCIEI...",
  "created_at": "2026-01-20T10:00:00Z",
  "is_active": true
}

Security Warning: The private key is only returned once when created. Store it securely - we cannot recover it.

GET POST /vendors/domain/ Auth Required

Verify ownership of your domain via DNS TXT record.

# Get verification token
curl https://attestiv.io/api/v1/vendors/domain/token/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Check verification status
curl https://attestiv.io/api/v1/vendors/domain/status/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Trigger verification check
curl -X POST https://attestiv.io/api/v1/vendors/domain/verify/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

headers = {"Authorization": f"Bearer {access_token}"}

# Get verification token
token_info = requests.get(
    "https://attestiv.io/api/v1/vendors/domain/token/",
    headers=headers
).json()
# Add TXT record: _attestiv.yourdomain.com -> token_info["token"]

# Trigger verification
result = requests.post(
    "https://attestiv.io/api/v1/vendors/domain/verify/",
    headers=headers
).json()
print(f"Verified: {result['is_verified']}")

const headers = { "Authorization": `Bearer ${accessToken}` };

// Get verification token
const tokenInfo = await fetch("https://attestiv.io/api/v1/vendors/domain/token/", {
  headers
}).then(r => r.json());
// Add TXT record: _attestiv.yourdomain.com -> tokenInfo.token

// Trigger verification
const result = await fetch("https://attestiv.io/api/v1/vendors/domain/verify/", {
  method: "POST",
  headers
}).then(r => r.json());
console.log(`Verified: ${result.is_verified}`);

DNS Setup: Add a TXT record at _attestiv.yourdomain.com with the verification token value.

Invoices

Sign invoices with cryptographic signatures and manage signed documents.

POST /invoices/sign/ Auth Required

Upload and sign an invoice file (PDF, PNG, JPEG, TIFF up to 10MB).

curl -X POST https://attestiv.io/api/v1/invoices/sign/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@invoice.pdf" \
  -F "key_id=sk_xyz789" \
  -F 'metadata={"invoice_number": "INV-2026-001", "amount": "5000.00", "currency": "USD"}'

import json

headers = {"Authorization": f"Bearer {access_token}"}

with open("invoice.pdf", "rb") as f:
    response = requests.post(
        "https://attestiv.io/api/v1/invoices/sign/",
        headers=headers,
        files={"file": ("invoice.pdf", f, "application/pdf")},
        data={
            "key_id": "sk_xyz789",
            "metadata": json.dumps({
                "invoice_number": "INV-2026-001",
                "amount": "5000.00",
                "currency": "USD"
            })
        }
    )

signed = response.json()
print(f"Verify URL: {signed['verify_url']}")

const formData = new FormData();
formData.append("file", fileInput.files[0]);
formData.append("key_id", "sk_xyz789");
formData.append("metadata", JSON.stringify({
  invoice_number: "INV-2026-001",
  amount: "5000.00",
  currency: "USD"
}));

const response = await fetch("https://attestiv.io/api/v1/invoices/sign/", {
  method: "POST",
  headers: { "Authorization": `Bearer ${accessToken}` },
  body: formData
});

const signed = await response.json();
console.log(`Verify URL: ${signed.verify_url}`);

Response

{
  "id": "inv_abc123",
  "file_hash": "sha256:a1b2c3d4e5f6...",
  "signature": "ed25519:MEUCIQDx...",
  "signed_at": "2026-01-20T10:30:00Z",
  "key_id": "sk_xyz789",
  "metadata": {
    "invoice_number": "INV-2026-001",
    "amount": "5000.00",
    "currency": "USD"
  },
  "verify_url": "https://attestiv.io/v/inv_abc123"
}

GET /invoices/ Auth Required

List all signed invoices for your account with pagination.

# List invoices (paginated)
curl "https://attestiv.io/api/v1/invoices/?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get specific invoice
curl https://attestiv.io/api/v1/invoices/inv_abc123/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

headers = {"Authorization": f"Bearer {access_token}"}

# List invoices
response = requests.get(
    "https://attestiv.io/api/v1/invoices/",
    headers=headers,
    params={"page": 1, "page_size": 20}
)
invoices = response.json()

# Get specific invoice
invoice = requests.get(
    "https://attestiv.io/api/v1/invoices/inv_abc123/",
    headers=headers
).json()

const headers = { "Authorization": `Bearer ${accessToken}` };

// List invoices
const invoices = await fetch(
  "https://attestiv.io/api/v1/invoices/?page=1&page_size=20",
  { headers }
).then(r => r.json());

// Get specific invoice
const invoice = await fetch(
  "https://attestiv.io/api/v1/invoices/inv_abc123/",
  { headers }
).then(r => r.json());

Verification

Public endpoints to verify signed invoices. No authentication required - anyone can verify.

POST /verify/invoice/ Public

Upload a file to verify its signature and authenticity.

curl -X POST https://attestiv.io/api/v1/verify/invoice/ \
  -F "file=@invoice.pdf"

with open("invoice.pdf", "rb") as f:
    response = requests.post(
        "https://attestiv.io/api/v1/verify/invoice/",
        files={"file": ("invoice.pdf", f, "application/pdf")}
    )

result = response.json()
if result["verified"]:
    print(f"✓ Verified! Signed by {result['vendor']['name']}")
else:
    print("✗ Not verified - invoice not found or tampered")

const formData = new FormData();
formData.append("file", fileInput.files[0]);

const response = await fetch("https://attestiv.io/api/v1/verify/invoice/", {
  method: "POST",
  body: formData
});

const result = await response.json();
if (result.verified) {
  console.log(`✓ Verified! Signed by ${result.vendor.name}`);
} else {
  console.log("✗ Not verified");
}

Response (Verified)

{
  "verified": true,
  "vendor": {
    "id": "vnd_abc123",
    "name": "Acme Corporation",
    "domain": "acme.com",
    "is_domain_verified": true,
    "verified_since": "2025-06-15"
  },
  "signed_at": "2026-01-20T10:30:00Z",
  "key_status": "valid",
  "metadata": {
    "invoice_number": "INV-2026-001"
  }
}

Response (Not Verified)

{
  "verified": false,
  "reason": "no_signature_found"
}

POST /verify/hash/ Public

Verify using a pre-computed SHA-256 hash (useful for large files or batch verification).

# First compute SHA-256 hash locally
FILE_HASH=$(sha256sum invoice.pdf | cut -d' ' -f1)

# Then verify
curl -X POST https://attestiv.io/api/v1/verify/hash/ \
  -H "Content-Type: application/json" \
  -d "{\"hash\": \"$FILE_HASH\"}"

import hashlib

# Compute hash locally
with open("invoice.pdf", "rb") as f:
    file_hash = hashlib.sha256(f.read()).hexdigest()

# Verify by hash
response = requests.post(
    "https://attestiv.io/api/v1/verify/hash/",
    json={"hash": file_hash}
)
result = response.json()

// Compute hash locally (using crypto-js or Web Crypto API)
const buffer = await file.arrayBuffer();
const hashBuffer = await crypto.subtle.digest("SHA-256", buffer);
const hashArray = Array.from(new Uint8Array(hashBuffer));
const fileHash = hashArray.map(b => b.toString(16).padStart(2, "0")).join("");

// Verify by hash
const response = await fetch("https://attestiv.io/api/v1/verify/hash/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ hash: fileHash })
});
const result = await response.json();

GET /verify/vendor/{vendor_id}/ Public

Get public information about a verified vendor.

curl https://attestiv.io/api/v1/verify/vendor/vnd_abc123/

vendor = requests.get(
    "https://attestiv.io/api/v1/verify/vendor/vnd_abc123/"
).json()

const vendor = await fetch(
  "https://attestiv.io/api/v1/verify/vendor/vnd_abc123/"
).then(r => r.json());

Response

{
  "id": "vnd_abc123",
  "name": "Acme Corporation",
  "domain": "acme.com",
  "is_domain_verified": true,
  "verified_since": "2025-06-15",
  "active_keys_count": 2,
  "total_signed_invoices": 1542
}

Customers

Manage customer accounts for receiving and verifying invoices.

POST /customers/register/ Public

Register a new customer account.

curl -X POST https://attestiv.io/api/v1/customers/register/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "buyer_inc",
    "email": "ap@buyer.com",
    "password": "secure_password_123",
    "name": "Buyer Inc."
  }'

response = requests.post(
    "https://attestiv.io/api/v1/customers/register/",
    json={
        "username": "buyer_inc",
        "email": "ap@buyer.com",
        "password": "secure_password_123",
        "name": "Buyer Inc."
    }
)
customer = response.json()

const response = await fetch("https://attestiv.io/api/v1/customers/register/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "buyer_inc",
    email: "ap@buyer.com",
    password: "secure_password_123",
    name: "Buyer Inc."
  })
});
const customer = await response.json();

GET /customers/me/ Auth Required

Get your customer profile.

curl https://attestiv.io/api/v1/customers/me/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

customer = requests.get(
    "https://attestiv.io/api/v1/customers/me/",
    headers={"Authorization": f"Bearer {access_token}"}
).json()

const customer = await fetch("https://attestiv.io/api/v1/customers/me/", {
  headers: { "Authorization": `Bearer ${accessToken}` }
}).then(r => r.json());

Banking Registry

Zero-knowledge encrypted banking details registry. Data is encrypted client-side before transmission.

POST /banking/details/ Auth Required

Store encrypted banking details. Data must be encrypted client-side using X25519 key exchange.

# Banking details must be encrypted client-side first
curl -X POST https://attestiv.io/api/v1/banking/details/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "encrypted_data": "BASE64_ENCRYPTED_PAYLOAD",
    "ephemeral_public_key": "X25519_EPHEMERAL_KEY",
    "nonce": "ENCRYPTION_NONCE"
  }'

from nacl.public import PrivateKey, PublicKey, Box
import base64
import json

# Your banking details (encrypt before sending!)
banking_data = {
    "bank_name": "First National Bank",
    "account_number": "1234567890",
    "routing_number": "021000021"
}

# Generate ephemeral key pair for this transaction
ephemeral_key = PrivateKey.generate()

# Encrypt with customer's public key (from their profile)
box = Box(ephemeral_key, customer_public_key)
nonce = nacl.utils.random(Box.NONCE_SIZE)
encrypted = box.encrypt(json.dumps(banking_data).encode(), nonce)

# Send encrypted data
response = requests.post(
    "https://attestiv.io/api/v1/banking/details/",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "encrypted_data": base64.b64encode(encrypted.ciphertext).decode(),
        "ephemeral_public_key": base64.b64encode(
            ephemeral_key.public_key.encode()
        ).decode(),
        "nonce": base64.b64encode(nonce).decode()
    }
)

// Using tweetnacl-js for encryption
import nacl from "tweetnacl";
import { encodeBase64 } from "tweetnacl-util";

const bankingData = {
  bank_name: "First National Bank",
  account_number: "1234567890",
  routing_number: "021000021"
};

// Generate ephemeral key pair
const ephemeralKeyPair = nacl.box.keyPair();

// Encrypt with customer's public key
const nonce = nacl.randomBytes(nacl.box.nonceLength);
const message = new TextEncoder().encode(JSON.stringify(bankingData));
const encrypted = nacl.box(message, nonce, customerPublicKey, ephemeralKeyPair.secretKey);

// Send encrypted data
await fetch("https://attestiv.io/api/v1/banking/details/", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    encrypted_data: encodeBase64(encrypted),
    ephemeral_public_key: encodeBase64(ephemeralKeyPair.publicKey),
    nonce: encodeBase64(nonce)
  })
});

Zero-Knowledge: Banking details are encrypted on your device before transmission. Attestiv cannot read or access your banking information.

POST /banking/grants/ Auth Required

Grant a customer access to view your encrypted banking details.

curl -X POST https://attestiv.io/api/v1/banking/grants/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_xyz789",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

response = requests.post(
    "https://attestiv.io/api/v1/banking/grants/",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "customer_id": "cust_xyz789",
        "expires_at": "2026-12-31T23:59:59Z"
    }
)
grant = response.json()

const grant = await fetch("https://attestiv.io/api/v1/banking/grants/", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    customer_id: "cust_xyz789",
    expires_at: "2026-12-31T23:59:59Z"
  })
}).then(r => r.json());

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format.

Error Response Format

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": { /* Optional additional context */ }
}

Common Status Codes

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Missing or invalid authentication
`403`	Forbidden	Authenticated but not authorized
`404`	Not Found	Resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Something went wrong on our end

Rate Limiting

API requests are limited to 100 requests per minute per API key. Check the X-RateLimit-Remaining header for your current quota.