Authentication - Penbox Documentation

The Connect API uses OAuth2 for authentication, allowing your application to access Penbox on behalf of users. This guide covers the complete authentication flow from initial authorization to token refresh.

Prerequisites

Before starting, you need:

Client ID: Your application identifier (e.g., my-app)
Client Secret: Secret key for authentication (provided by Penbox)
Redirect URI: HTTPS URL where users will be sent after authorization

Keep your client_secret secure! Never expose it in client-side code or public repositories.

OAuth2 Flow Overview

The authentication process follows the standard OAuth2 Authorization Code flow:

Step 1: Redirect to Authorization

Create a “Connect Penbox” button in your application that redirects users to:

https://connect.penbox.io/authorize?client_id={client_id}&redirect_uri={redirect_uri}&state={state}

Parameters

Parameter	Required	Description
`client_id`	Yes	Your client ID provided by Penbox
`redirect_uri`	Yes	HTTPS URL where users will be redirected after authorization
`state`	No	Random string to prevent CSRF attacks (recommended)
`response_type`	No	Grant type: `code` (default) or `token`
`scope`	No	Requested scopes, default: `offline_access`

Example Redirect

<a href="https://connect.penbox.io/authorize?client_id=my-app&redirect_uri=https://myapp.com/callback&state=random123">
  Connect Penbox Account
</a>

Or programmatically:

const authUrl = new URL('https://connect.penbox.io/authorize');
authUrl.searchParams.set('client_id', 'my-app');
authUrl.searchParams.set('redirect_uri', 'https://myapp.com/callback');
authUrl.searchParams.set('state', generateRandomState());

window.location.href = authUrl.toString();

Step 2: User Authorization

After redirection, the user will:

Log in to Penbox (if not already logged in)
Select a company (workspace) to authorize
Approve your application’s access request

The authorization page shows:

Your application name
Which company they’re authorizing
What permissions you’re requesting

Step 3: Handle Redirect Callback

After authorization, the user is redirected back to your redirect_uri with query parameters.

Success Response

https://myapp.com/callback?code=ABC123XYZ&state=random123

Parameter	Description
`code`	Authorization code to exchange for tokens (valid for 10 minutes)
`state`	The state you provided (verify this matches!)

Error Response

https://myapp.com/callback?error=access_denied&error_description=User+denied+access&state=random123

Parameter	Description
`error`	Error code (e.g., `access_denied`, `unauthorized_client`)
`error_description`	Human-readable error description
`state`	The state you provided

Always verify the state parameter matches what you sent to prevent CSRF attacks.

Step 4: Exchange Code for Tokens

Exchange the authorization code for an access token by making a POST request to /token.

Request

POST https://connect.penbox.io/token
Content-Type: application/json

{
  "client_id": "my-app",
  "client_secret": "your-secret-key",
  "grant_type": "authorization_code",
  "code": "ABC123XYZ",
  "redirect_uri": "https://myapp.com/callback",
  "custom_data": {
    "user_id": "12345",
    "account_email": "[email protected]"
  }
}

Parameters

Parameter	Required	Description
`client_id`	Yes	Your client ID
`client_secret`	Yes	Your client secret
`grant_type`	Yes	Must be `authorization_code`
`code`	Yes	The authorization code received
`redirect_uri`	Yes	Must match the redirect_uri from step 1
`custom_data`	No	Arbitrary data stored with the authorization

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "B1M0YS2OBDg+MNnVXGholK1pJeCt4+SB6LVN71KqZ3NLAC0...",
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expiresIn": 86400
}

Field	Description
`access_token`	JWT token to use for API requests (valid for 24 hours)
`refresh_token`	Token to get a new access_token when it expires
`id_token`	JWT with user information (optional)
`token_type`	Always `Bearer`
`expiresIn`	Token lifetime in seconds (86400 = 24 hours)

The refresh_token is only provided if you requested the offline_access scope (which is the default).

Step 5: Use Access Token

Include the access token in the Authorization header for all API requests:

GET https://connect.penbox.io/v1/requests
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example: Create a Request

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

Refreshing Access Tokens

Access tokens expire after 24 hours. Use the refresh token to get a new access token without requiring user re-authorization.

Request

POST https://connect.penbox.io/token
Content-Type: application/json

{
  "client_id": "my-app",
  "client_secret": "your-secret-key",
  "grant_type": "refresh_token",
  "refresh_token": "B1M0YS2OBDg+MNnVXGholK1pJeCt4+SB6LVN71KqZ3NLAC0..."
}

Parameters

Parameter	Required	Description
`client_id`	Yes	Your client ID
`client_secret`	Yes	Your client secret
`grant_type`	Yes	Must be `refresh_token`
`refresh_token`	Yes	The refresh token received during authorization

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expiresIn": 86400
}

Refresh tokens are long-lived but can be invalidated if:

User revokes authorization
Client credentials are regenerated
Security policy requires re-authentication

Custom Data

The custom_data field in the token exchange allows you to store arbitrary data with the authorization. This is useful for linking Penbox accounts to your system’s users.

Example Use Cases

Store User Reference

{
  "custom_data": {
    "user_id": "12345",
    "account_email": "[email protected]"
  }
}

Store Account Information

{
  "custom_data": {
    "company_id": "ABC-Corp",
    "subscription_tier": "premium",
    "integration_date": "2024-01-15"
  }
}

This data is stored in Penbox and can be retrieved when needed for reference or debugging.

Grant Types

The Connect API supports two OAuth2 grant types:

Authorization Code (Recommended)

Use for: Server-side applications where you can securely store the client_secret.

response_type=code

Provides both access_token and refresh_token for long-term access.

Implicit Grant

Use for: Client-side applications (SPAs) where client_secret cannot be stored securely.

response_type=token

Returns access_token directly in the redirect URL fragment. No refresh_token is provided.

The implicit grant is less secure and should only be used when absolutely necessary. Prefer authorization code flow for all server-side applications.

Token Security

Storing Tokens

Access Tokens

Store securely server-side (encrypted database, secure session)
Never expose in client-side code or URLs
Rotate regularly (every 24 hours via refresh)

Refresh Tokens

Treat as highly sensitive credentials
Encrypt at rest in your database
Never send to client-side code
Implement rotation on refresh

Revoking Access

Users can revoke your application’s access at any time through their Penbox account settings. When this happens:

All access tokens are immediately invalidated
Refresh tokens no longer work
API requests return 401 Unauthorized
You should prompt the user to re-authorize

Error Responses

Authorization Errors

Error Code	Description	Action
`access_denied`	User denied authorization	Inform user, allow retry
`unauthorized_client`	Invalid client_id or redirect_uri	Check configuration
`invalid_request`	Missing or invalid parameters	Fix request parameters
`server_error`	Penbox internal error	Retry later

Token Exchange Errors

Error Code	Description	Action
`invalid_grant`	Invalid or expired authorization code	Request new authorization
`invalid_client`	Invalid client credentials	Check client_id and client_secret
`unauthorized_client`	Client not authorized for this grant type	Contact Penbox support

Best Practices

Use state parameter

Always include a random state parameter and verify it matches on the callback to prevent CSRF attacks.

Implement token refresh

Proactively refresh access tokens before they expire (e.g., after 23 hours) to avoid API disruptions.

Handle errors gracefully

Implement proper error handling for authorization failures, token expiration, and revocation.

Store tokens securely

Never expose tokens in client-side code, URLs, or logs. Encrypt refresh tokens at rest.

Request minimal scopes

Only request the scopes your application actually needs.

Monitor token usage

Track token usage and expiration to detect issues early.

Next Steps

Create Requests

Learn how to create form requests

List Companies

Retrieve authorized companies

API Reference

Explore all API endpoints

Error Handling

Handle API errors properly

API Reference

Forms

Files

Workspaces

​Prerequisites

​OAuth2 Flow Overview

​Step 1: Redirect to Authorization

​Parameters

​Example Redirect

​Step 2: User Authorization

​Step 3: Handle Redirect Callback

​Success Response

​Error Response

​Step 4: Exchange Code for Tokens

​Request

​Parameters

​Response

​Step 5: Use Access Token

​Example: Create a Request

​Refreshing Access Tokens

​Request

​Parameters

​Response

​Custom Data

​Example Use Cases

​Grant Types

​Authorization Code (Recommended)

​Implicit Grant

​Token Security

​Storing Tokens

​Revoking Access

​Error Responses

​Authorization Errors

​Token Exchange Errors

​Best Practices

​Next Steps

Create Requests

List Companies

API Reference

Error Handling

Prerequisites

OAuth2 Flow Overview

Step 1: Redirect to Authorization

Parameters

Example Redirect

Step 2: User Authorization

Step 3: Handle Redirect Callback

Success Response

Error Response

Step 4: Exchange Code for Tokens

Request

Parameters

Response

Step 5: Use Access Token

Example: Create a Request

Refreshing Access Tokens

Request

Parameters

Response

Custom Data

Example Use Cases

Grant Types

Authorization Code (Recommended)

Implicit Grant

Token Security

Storing Tokens

Revoking Access

Error Responses

Authorization Errors

Token Exchange Errors

Best Practices

Next Steps