Developer Guide

Build and operate a production integration with Inklok.

This guide covers integration best practices, security, testing, and production readiness for applications that create and manage agreements with Inklok.

Authentication

API keys are used for server-to-server integrations. Bearer tokens are used where applicable, including recipient signing flows. Never expose credentials in client-side applications, store them in secure secret storage, and grant only the permissions your integration needs.

Sandbox Environment

Purpose

Use Sandbox to build integrations, test agreement flows, validate application behavior, and experiment before launching production traffic. Agreement workflows behave like production workflows, but email delivery is simulated.

Isolation

Sandbox data is isolated from production data. Sandbox agreements, documents, and simulated activity do not affect production agreements.

Sandbox Inbox

Purpose

Sandbox includes a simulated delivery environment for testing agreement workflows without sending real emails.

When an agreement action would normally send a notification to a party, Inklok creates a simulated email in Sandbox Inbox instead. This allows you to validate recipient communications, agreement lifecycle flows, and application behavior before enabling production delivery.

Behavior

Sandbox emails are simulated only and are not sent to recipients.

Sandbox Inbox contains simulated emails generated by sandbox agreement activity, including events such as:

• Agreement invitations
• Signing requests
• Completion notifications
• Other agreement-related communications

Simulated emails use the same notification templates and lifecycle triggers as production notifications, but they are available only in Sandbox Inbox for testing and review.

Development Flow

Use Sandbox Inbox to:

• Verify your integration triggers the expected notifications.
• Confirm agreement lifecycle behavior.
• Test recipient communication flows.
• Validate your application's handling of agreement events.

Before moving to production, replace sandbox credentials with production credentials and verify that your notification workflows behave as expected with real recipients.

Credentials

Use sandbox credentials while developing and testing. Use production credentials only for production agreement flows.

Development Flow

1. Create or access a sandbox organization.
2. Generate sandbox credentials.
3. Build and test agreement flows.
4. Review simulated emails in Sandbox Inbox.
5. Validate agreement lifecycle behavior.
6. Move to production credentials when ready.

Production Readiness

• Replace sandbox credentials with production credentials.
• Verify API integrations.
• Confirm agreement status and activity monitoring.
• Validate error handling.
• Monitor production activity.

Security Best Practices

• Protect API keys and bearer tokens.
• Rotate credentials on a regular schedule and immediately after suspected exposure.
• Never commit secrets to source control.
• Use secure secret storage in your deployment platform.
• Limit access to the minimum permissions required.

Error Handling

Integrations should handle API errors gracefully and show actionable recovery paths to operators or end users.

Status	Meaning
200	Success
201	Created
400	Invalid request
401	Authentication failure
403	Permission denied
404	Resource not found
409	Conflict
429	Rate limited
500	Server error

Retry Guidance

Retry transient failures with exponential backoff and jitter. Avoid retry loops that create duplicate agreements or duplicate notifications. For requests that accept an idempotency key, reuse the same key when retrying the same logical request.

Monitoring Agreement Progress

Use the Agreement and Agreement Events endpoints to monitor agreement progress. Poll at a reasonable interval, store the latest processed event, and make your own processing idempotent so repeated reads do not create duplicate work.

Production Checklist

• Use production API credentials.
• Secure credentials in secret storage.
• Validate error handling.
• Monitor integration health.
• Confirm agreement status and activity monitoring.