Authentication

Bearer Token

All API requests must include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer dh_live_abc123def456...

Requests without a valid key receive a 401 Unauthorized response.

Key Format

DocuHub API keys follow a predictable format that makes them easy to identify in logs and secret scanners:

dh_live_<random>

Examples:
  dh_live_sk7Gx2mP9qRtW4nB8vJ6yZ
  dh_live_aB3cD5eF7gH9iJ1kL3mNpQ

The dh_live_ prefix indicates a production key. Keys are 32 characters long including the prefix.

Scopes

Each key is created with a scope that limits which endpoints it can access. Use the narrowest scope that satisfies your needs.

If a key attempts to access an endpoint outside its scope, the API returns a 403 insufficient_scope error.

IP Allowlist

For additional security, you can restrict each API key to a set of IP addresses or CIDR ranges. Requests from unlisted IPs receive a 403 ip_not_allowed error.

Configure allowed IPs when creating or editing a key in your Developer Settings. Supported formats:

Single IP:    203.0.113.42
CIDR range:   10.0.0.0/24
IPv6:         2001:db8::1

Key Rotation

We recommend rotating your keys periodically. DocuHub supports a seamless rotation workflow:

1. Create a new key with the same scope and IP allowlist.
2. Deploy the new key to your application.
3. Verify traffic is using the new key (check the key's "Last Used" timestamp).
4. Revoke the old key.

Both keys remain valid simultaneously, so there is zero downtime during the rotation window.

Security Best Practices

# .env (never commit this file)
DOCUHUB_API_KEY=dh_live_sk7Gx2mP9qRtW4nB8vJ6

# In your code
const apiKey = process.env.DOCUHUB_API_KEY;