API Authentication

Learn how to authenticate your E-Sign API requests to Penvio.

Overview

The Penvio E-Sign API uses API key authentication. You’ll need to include your API key in the Authorization header of every request.

Obtaining an API Key

API Key Format

API keys follow the format:

pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• pk_ prefix identifies it as a Penvio API key
• live_ indicates a production key (vs test_ for sandbox)
• The remaining characters are a unique identifier

Using the API Key

Include your key in the Authorization header as a Bearer token:

Authorization: Bearer pk_live_xxxxxxxxxxxxx

Examples

curl -X GET https://penvio.io/api/v1/esign/templates \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

// Using fetch
const response = await fetch('https://penvio.io/api/v1/esign/templates', {
  headers: {
    'Authorization': `Bearer ${process.env.PENVIO_API_KEY}`,
    'Content-Type': 'application/json',
  },
});
 
const { data } = await response.json();
 
// Using axios
import axios from 'axios';
 
const client = axios.create({
  baseURL: 'https://penvio.io/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.PENVIO_API_KEY}`,
  },
});
 
const { data } = await client.get('/esign/templates');

import os
import requests
 
API_KEY = os.environ['PENVIO_API_KEY']
BASE_URL = 'https://penvio.io/api/v1'
 
headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json',
}
 
response = requests.get(f'{BASE_URL}/esign/templates', headers=headers)
data = response.json()

package main
 
import (
    "net/http"
    "os"
)
 
func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://penvio.io/api/v1/esign/templates", nil)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("PENVIO_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
 
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

API Key Management

Viewing Keys

View all API keys in Organization Settings → API Keys. You’ll see:

• Key name
• Creation date
• Last used date
• Key prefix (for identification)

Revoking Keys

To revoke a compromised or unused key:

1. Go to Organization Settings → API Keys
2. Click Revoke on the key
3. Confirm the action

Multiple Keys

Create separate keys for different environments and purposes:

This way, if one key is compromised, you only need to revoke that specific key.

Error Responses

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

This means:

• No API key was provided
• The API key is invalid or revoked
• The Authorization header format is incorrect

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Enterprise subscription required"
  }
}

This means:

• Your organization doesn’t have an Enterprise subscription
• BYOB storage is not configured
• The API key doesn’t have permission for the requested resource

Best Practices

1. Use environment variables

   export PENVIO_API_KEY="pk_live_xxxxxxxxxxxxx"

2. Create a wrapper function

   async function penvioFetch(path, options = {}) {
     const response = await fetch(`https://penvio.io/api/v1${path}`, {
       ...options,
       headers: {
         'Authorization': `Bearer ${process.env.PENVIO_API_KEY}`,
         'Content-Type': 'application/json',
         ...options.headers,
       },
     });
    
     if (!response.ok) {
       const error = await response.json();
       throw new Error(error.error?.message || 'API request failed');
     }
    
     return response.json();
   }

3. Handle errors gracefully

   • Monitor for 401 responses and alert on auth failures
   • Implement retry logic for transient errors
   • Log API errors for debugging

4. Audit regularly

   • Review API key usage in the organization dashboard
   • Rotate keys periodically (recommended: every 90 days)
   • Remove unused keys promptly

5. Use the principle of least privilege

   • Create separate keys for different services
   • Revoke keys when no longer needed

Next Steps

• API Endpoints - Explore available API endpoints
• Rate Limits - Understand API usage limits
• Error Handling - Handle API errors gracefully
• Getting Started - Set up your Penvio account