Authentication

PDFDancer uses API tokens to authenticate requests. You can get started immediately with anonymous tokens, or create an account for higher limits and advanced features.

---

Anonymous Tokens (Quick Start)

No API token needed to get started—the SDK automatically obtains an anonymous token when you don't provide one:

Python

from pdfdancer import PDFDancer

# No token needed! SDK automatically gets an anonymous token
with PDFDancer.open("input.pdf") as pdf:
    # Your PDF operations here
    pass

TypeScript

import { PDFDancer } from 'pdfdancer-client-typescript';

// No token needed! SDK automatically gets an anonymous token
const pdf = await PDFDancer.open('input.pdf');

Java

// No token needed! SDK automatically gets an anonymous token
PDFDancer pdf = PDFDancer.createSession("input.pdf");
// Your PDF operations here

Anonymous tokens are perfect for prototyping and small projects. For production use, higher rate limits, and access to premium features, create an account and use authenticated API tokens.

---

Obtaining an API Token

1. Sign into the PDFDancer Dashboard.
2. Navigate to Settings → API Tokens.
3. Click Generate Token, provide a descriptive name, and copy the generated token.

Store tokens in a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or your CI provider's encrypted variables. Never commit tokens to source control.

---

Authentication Methods

Environment Variables (Recommended)

Set the token in an environment variable to avoid hardcoding credentials:

export PDFDANCER_TOKEN="your-api-token"

The SDK will automatically read this environment variable when initializing.

Python

from pdfdancer import PDFDancer

# Token is automatically read from PDFDANCER_TOKEN environment variable
with PDFDancer.open("input.pdf") as pdf:
    # Your PDF operations here
    pass

TypeScript

import { PDFDancer } from 'pdfdancer-client-typescript';

// Token is automatically read from PDFDANCER_TOKEN environment variable
const pdf = await PDFDancer.open('input.pdf');

Java

// Token is automatically read from PDFDANCER_TOKEN environment variable
PDFDancer pdf = PDFDancer.createSession("input.pdf");
// Your PDF operations here

Explicit Token Parameter

You can also pass the token explicitly when creating the client:

Python

from pdfdancer import PDFDancer

with PDFDancer.open(
    pdf_data="input.pdf",
    token="your-api-token"
) as pdf:
    # Your PDF operations here
    pass

TypeScript

import { PDFDancer } from 'pdfdancer-client-typescript';

const pdf = await PDFDancer.open('input.pdf', 'your-api-token');

Java

// Java client does not require explicit token parameter
// Token is automatically read from PDFDANCER_TOKEN environment variable
// Set via: export PDFDANCER_TOKEN="your-api-token"
// Or via system property: -DPDFDANCER_TOKEN="your-api-token"
PDFDancer pdf = PDFDancer.createSession("input.pdf");
// Your PDF operations here

---

Configuration Options

Custom API Endpoint

This configuration is for self-hosted enterprise plans. If you're using a self-hosted instance of PDFDancer, you can override the default API endpoint by setting the PDFDANCER_BASE_URL environment variable or passing the base_url parameter:

Python

from pdfdancer import PDFDancer

# Using environment variable
# export PDFDANCER_BASE_URL="https://sandbox.pdfdancer.com"

# Or passing explicitly
with PDFDancer.open(
    pdf_data="input.pdf",
    token="your-api-token",
    base_url="https://sandbox.pdfdancer.com"
) as pdf:
    pass

TypeScript

import { PDFDancer } from 'pdfdancer-client-typescript';

// Using environment variable
// export PDFDANCER_BASE_URL="https://sandbox.pdfdancer.com"

// Or passing explicitly
const pdf = await PDFDancer.open(
  'input.pdf',
  'your-api-token',
  'https://sandbox.pdfdancer.com'
);

Java

// Set via system properties or environment variable
// export PDFDANCER_BASE_URL="https://sandbox.pdfdancer.com"
// or -DPDFDANCER_BASE_URL="https://sandbox.pdfdancer.com"

PDFDancer pdf = PDFDancer.createSession("input.pdf");

Request Timeout

Configure request timeout for long-running operations:

Python

from pdfdancer import PDFDancer

with PDFDancer.open(
    pdf_data="input.pdf",
    token="your-api-token",
    timeout=60  # 60 seconds
) as pdf:
    pass

TypeScript

import { PDFDancer } from 'pdfdancer-client-typescript';

const pdf = await PDFDancer.open(
  'input.pdf',
  'your-api-token',
  'https://api.pdfdancer.com',
  60000  // 60 seconds in milliseconds
);

Java

// Configure timeout via system properties
// Set via: -DPDFDANCER_TIMEOUT="60000" (milliseconds)
// or environment variable: PDFDANCER_TIMEOUT

PDFDancer pdf = PDFDancer.createSession("input.pdf");

---

Security Best Practices

Token Storage

• Never commit tokens to version control - Use .gitignore to exclude token files
• Use secrets managers - Store tokens in AWS Secrets Manager, HashiCorp Vault, or similar
• Environment-specific tokens - Use different tokens for development, staging, and production
• Rotate regularly - Generate new tokens periodically and deactivate old ones

Token Rotation

1. Generate a new token in the PDFDancer Dashboard
2. Update your environment variables or secrets manager
3. Deploy the changes to all environments
4. Deactivate the old token after verifying the new one works

Compromised Tokens

If a token is compromised:

1. Immediately deactivate it in the PDFDancer Dashboard
2. Generate a new token
3. Update all applications using the old token
4. Review audit logs for suspicious activity

---

Next Steps

• Quickstart – Make your first API calls
• Selecting Content – Learn how to find content in PDFs
• Examples – See complete working examples