Authentication - Penbox Documentation

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

Click the “Create API Token” button
Give your token a descriptive name (e.g., “Production Integration”, “Development”, “Analytics Tool”)
Select the workspace you want to authorize
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'

const response = await fetch('https://connect.penbox.io/v1/cases', {
  headers: {
    'Authorization': `Bearer ${apiToken}`
  }
});

const forms = await response.json();

import requests

headers = {
    'Authorization': f'Bearer {api_token}'
}

response = requests.get(
    'https://connect.penbox.io/v1/forms',
    headers=headers
)

forms = response.json()

<?php
$token = 'pnbx_1234567890abcdef1234567890abcdef1234567890abcdef';

$ch = curl_init('https://connect.penbox.io/v1/forms');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$forms = json_decode($response, true);

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: 'client@example.com',
      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

Store tokens securely

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

Use environment variables

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 regularly

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

Use descriptive names

Give your tokens meaningful names to track usage:

✅ “Production API - CRM Integration”
✅ “Development Environment”
✅ “Analytics Dashboard”
❌ “Token 1”, “Test”, “My Token”

Monitor token usage

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:

Go to app.penbox.io/workspace/settings/api
Find the token you want to revoke
Click the “Revoke” button
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:

Verify the token format
- Token should start with pnbx_
- No extra spaces or newlines
- Complete token copied
Check the Authorization header
Authorization: Bearer pnbx_your_token_here
- Includes “Bearer ” prefix with a space
- Token immediately after the space
Verify token is active
- Check app.penbox.io/workspace/settings/api
- Ensure token hasn’t been revoked
- Confirm token exists in the list

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:

Check this documentation for troubleshooting steps
Verify your token at app.penbox.io/workspace/settings/api
Test with the cURL examples above
Contact support at support@penbox.io with:
- Token name (never send the actual token)
- Error messages received
- API endpoint being called
- Request timestamp

​Getting Your API Token

​Step 1: Access API Settings

​Step 2: Create a New Token

​Token Format

​Using Your API Token

​Example Requests

​Making Authenticated Requests

​Token Scopes and Permissions

​Token Security

​Best Practices

​What NOT to Do

​Managing Tokens

​Viewing Active Tokens

​Revoking Tokens

​Token Lifecycle

​Authentication Errors

​Common Error Responses

​401 Unauthorized - Missing Token

​401 Unauthorized - Invalid Token

​403 Forbidden - No Access

​Debugging Authentication Issues

​Rate Limiting

​Rate Limit Exceeded

​Best Practices for Rate Limiting

​Testing Your Authentication

​Quick Test

​Integration Checklist

​Multiple Environments

​Development

​Staging

​Production

​Next Steps

Create Forms

List Workspaces

API Overview

All Endpoints

​Support

Getting Your API Token

Step 1: Access API Settings

Step 2: Create a New Token

Token Format

Using Your API Token

Example Requests

Making Authenticated Requests

Token Scopes and Permissions

Token Security

Best Practices

What NOT to Do

Managing Tokens

Viewing Active Tokens

Revoking Tokens

Token Lifecycle

Authentication Errors

Common Error Responses

401 Unauthorized - Missing Token

401 Unauthorized - Invalid Token

403 Forbidden - No Access

Debugging Authentication Issues

Rate Limiting

Rate Limit Exceeded

Best Practices for Rate Limiting

Testing Your Authentication

Quick Test

Integration Checklist

Multiple Environments

Development

Staging

Production

Next Steps

Support