Skip to main content
The API uses Bearer token authentication for all requests. This simple and secure method requires you to include your API token in the Authorization header of every request.

​
Getting Your API Token

​
Step 1: Access API Settings

Navigate to your Penbox API settings page: 
https://app.penbox.io/workspace/settings/api

​
Step 2: Create a New Token

  1. Click the “Create API Token” button
  2. Give your token a descriptive name (e.g., “Production Integration”, “Development”, “Analytics Tool”)
  3. Select the workspace you want to authorize
  4. Copy the generated token immediately
Important: Your API token will only be displayed once. Copy it immediately and store it securely. If you lose it, you’ll need to generate a new token.

​
Token Format

Your API token will look like this: 
pnbx_1234567890abcdef1234567890abcdef1234567890abcdef
Tokens always start with the pnbx_ prefix.

​
Using Your API Token

Include your API token in the Authorization header of every API request using the Bearer scheme: 
Authorization: Bearer pnbx_1234567890abcdef1234567890abcdef1234567890abcdef

​
Example Requests

curl -X GET 'https://connect.penbox.io/v1/workspaces' \
  -H 'Authorization: Bearer pnbx_1234567890abcdef1234567890abcdef1234567890abcdef'

​
Making Authenticated Requests

Every API endpoint requires authentication. Here’s an example creating a form request: 
const apiToken = 'pnbx_1234567890abcdef1234567890abcdef1234567890abcdef';

const response = await fetch('https://connect.penbox.io/v1/forms', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    flow: { slug: 'client-onboarding' },
    user: {
      email: '[email protected]',
      given_name: 'John',
      family_name: 'Doe'
    }
  })
});

const form = await response.json();
console.log('Form created:', form.id);

​
Token Scopes and Permissions

Each API token is associated with a specific workspace. The token will have access to:
  • All forms in the workspace
  • All cases in the workspace
  • All form templates enabled for the workspace
  • All files and attachments in the workspace
  • Document intelligence features for the workspace
Tokens are workspace-specific. If you need to access multiple workspaces, create a separate token for each one.

​
Token Security

​
Best Practices

  • Never commit tokens to version control (Git, SVN, etc.)
  • Store tokens in environment variables or secure credential management systems
  • Use secrets management services (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Never expose tokens in client-side code or browser JavaScript
Store your API token in environment variables:
.env
PENBOX_API_TOKEN=pnbx_1234567890abcdef1234567890abcdef1234567890abcdef
Then load it in your application:
const apiToken = process.env.PENBOX_API_TOKEN;
  • Rotate tokens periodically for enhanced security
  • Create a new token before revoking the old one to avoid downtime
  • Update all applications using the old token
  • Revoke the old token once migration is complete
Give your tokens meaningful names to track usage:
  • ✅ “Production API - CRM Integration”
  • ✅ “Development Environment”
  • ✅ “Analytics Dashboard”
  • ❌ “Token 1”, “Test”, “My Token”
  • Track which applications use which tokens
  • Monitor for unexpected API usage patterns
  • Set up alerts for unusual activity
  • Revoke tokens immediately if compromised

​
What NOT to Do

Never:
  • Commit tokens to Git repositories
  • Share tokens via email, chat, or screenshots
  • Store tokens in plain text files
  • Use the same token across multiple environments
  • Hardcode tokens in your source code
  • Post tokens in public forums or documentation

​
Managing Tokens

​
Viewing Active Tokens

Visit app.penbox.io/workspace/settings/api to see all your active API tokens:
  • Token name
  • Creation date
  • Last used date
  • Associated workspace

​
Revoking Tokens

To revoke a token:
  1. Go to app.penbox.io/workspace/settings/api
  2. Find the token you want to revoke
  3. Click the “Revoke” button
  4. Confirm the action
Once revoked, a token is immediately invalidated. All API requests using that token will fail with a 401 Unauthorized error.

​
Token Lifecycle

​
Authentication Errors

​
Common Error Responses

​
401 Unauthorized - Missing Token

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing authorization header"
}
Cause: The Authorization header is missing from your request. Solution: Add the Authorization header with your Bearer token.

​
401 Unauthorized - Invalid Token

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid token"
}
Cause: The token is invalid, expired, or has been revoked. Solution: Check your token is correct, or create a new token if it was revoked.

​
403 Forbidden - No Access

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "No access to this resource"
}
Cause: Your token doesn’t have access to the requested resource (e.g., wrong workspace). Solution: Verify you’re using the correct token for the workspace you’re trying to access.

​
Debugging Authentication Issues

If you’re experiencing authentication issues:
  1. Verify the token format
    • Token should start with pnbx_
    • No extra spaces or newlines
    • Complete token copied
  2. Check the Authorization header 
    Authorization: Bearer pnbx_your_token_here
    • Includes “Bearer ” prefix with a space
    • Token immediately after the space
  3. Verify token is active
  4. Test with cURL 
    curl -v -X GET 'https://connect.penbox.io/v1/workspaces' \
  -H 'Authorization: Bearer YOUR_TOKEN'
    The -v flag shows detailed request/response information.

​
Rate Limiting

API tokens are subject to rate limiting to ensure fair usage and system stability.

​
Rate Limit Exceeded

If you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later.",
  "retryAfter": 60
}

​
Best Practices for Rate Limiting

  • Cache responses when possible
  • Implement exponential backoff on errors
  • Monitor your usage patterns
  • Spread requests over time instead of bursting
  • Use webhooks instead of polling when possible

​
Testing Your Authentication

​
Quick Test

Test your token with a simple request to list workspaces: 
curl -X GET 'https://connect.penbox.io/v1/workspaces' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Expected response (success): 
{
  "data": [
    {
      "id": "...",
      "slug": "my-workspace",
      "name": "My Workspace"
    }
  ]
}
Error response (invalid token): 
{
  "statusCode": 401,
  "error": "Unauthorized"
}

​
Integration Checklist

Before deploying to production:
  • Token stored securely (environment variable or secrets manager)
  • Authorization header correctly formatted
  • Error handling implemented for 401/403 responses
  • Rate limiting handled with backoff strategy
  • Token name clearly identifies the integration
  • Monitoring/logging in place for API usage
  • Token rotation plan documented

​
Multiple Environments

For different environments, create separate tokens:

​
Development

PENBOX_API_TOKEN_DEV=pnbx_dev_token_here

​
Staging

PENBOX_API_TOKEN_STAGING=pnbx_staging_token_here

​
Production

PENBOX_API_TOKEN_PROD=pnbx_production_token_here
Then load the appropriate token based on your environment: 
const apiToken = process.env.NODE_ENV === 'production'
  ? process.env.PENBOX_API_TOKEN_PROD
  : process.env.PENBOX_API_TOKEN_DEV;

​
Next Steps

Create Forms

Learn how to create forms

List Workspaces

Retrieve your authorized workspaces

API Overview

Complete API capabilities guide

All Endpoints

Browse all available endpoints

​
Support

If you encounter issues with authentication:
  1. Check this documentation for troubleshooting steps
  2. Verify your token at app.penbox.io/workspace/settings/api
  3. Test with the cURL examples above
  4. Contact support at [email protected] with:
    • Token name (never send the actual token)
    • Error messages received
    • API endpoint being called
    • Request timestamp