API credentials consist of a Client ID and Client Secret pair that authenticate your external systems and applications when integrating with Docupath. Credentials are generated and managed in the Destination Format and APIs section of Settings and are restricted to administrators.
The Client Secret is displayed only once at generation time and must be securely stored; subsequent access requires key rotation to retrieve a new credential pair.
How It Works
Accessing the API Credentials Interface
Navigate to Settings in the main menu
Select Destination Format and APIs
Locate the API Credentials section
View existing credentials and key rotation history
Generating New API Credentials
Click the Generate API Credentials button
Enter a Key Name using a descriptive naming convention:
Environment-focused:
ERP Prod,Tax Authority Sandbox,Data Lake DevSystem-focused:
SAP Integration Key,Salesforce Export,Warehouse FeedPurpose-focused:
Invoice Processing,Vendor Master Sync
Click Create to create the credential pair
The system displays:
Client ID: A unique identifier for your credentials (can be shared safely)
Client Secret: A sensitive token (shown once only)
Copy both values immediately and store them securely
Storing Credentials Securely
Never hardcode credentials in source code or configuration files
Store credentials in a Secrets Manager:
AWS Secrets Manager
Azure Key Vault
HashiCorp Vault
1Password, LastPass, or similar vault solution
Grant access on a least-privilege basis:
Only the service/application needing the credentials gets access
Rotate credentials quarterly or upon employee departure
Audit logs should track all credential access and usage
Using Credentials in API Requests
The Docupath API uses OAuth 2.0. Your Client ID and Client Secret are not sent on every request. Instead, you exchange them for a short-lived access token, which is then used to authenticate individual API calls.
Request an access token from the OAuth 2.0 token endpoint:
A successful request returns: - Endpoint: POST https://api.docupath.app/v1/oauth/token - Headers: - Content-Type: application/x-www-form-urlencoded - Authorization: Basic {base64(CLIENT_ID:CLIENT_SECRET)} - Body: - grant_type=client_credentials
{
"access_token": "eyJ0eXAiOiJKV1...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "13823c0df1..."
}Use the access token in subsequent API requests via the
Authorizationheader:
Authorization: Bearer {ACCESS_TOKEN}Handle token expiry: Access tokens are short-lived (see
expires_in, e.g. 3600 seconds). When a token expires, obtain a new one using the OAuth 2.0 refresh token flow or by re-authenticating with the Client Credentials grant.Invalid client credentials return an error such as
invalid_client("Client authentication failed"). Requests made with a missing, invalid, or expired access token are rejected.
Key Rotation Workflow
The recommended key rotation process ensures zero downtime and maintains audit compliance:
Generate a new credential pair:
Follow the "Generating New API Credentials" steps above
Note the new Client ID and Secret
Add a suffix or timestamp to the key name to differentiate from the old key
Update external systems:
Deploy the new credentials to all systems using the old credentials
Systems should use configuration management to switch without code changes
Test thoroughly in sandbox environments first
Verify the new credentials are working:
Monitor logs for successful API calls using the new Client ID
Confirm no authentication errors from the new credentials
Test both read and write operations (if applicable)
Delete the old credentials:
Once verified that new credentials are fully operational, delete the old pair
This prevents accidental usage of outdated credentials
Deletion is irreversible; the credential pair cannot be recovered
Document the rotation:
Record the rotation date, reason, and systems affected
Update access control records and credential inventories
Notify teams who manage dependent systems
Naming Convention Best Practices
Use clear, descriptive key names for easier management:
Naming Pattern | Example | Use Case |
Environment + System |
| Multi-environment deployments |
System + Purpose |
| Multiple integrations per system |
Date + Identifier |
| Time-based tracking |
Functional Area |
| Department-specific integrations |
Multi-Credential Scenarios
You may generate multiple credential pairs for:
Different environments: Production, staging, development
Different applications: ERP, tax system, data warehouse, marketplace
Different purposes: Read-only reporting, full CRUD operations, webhook receivers
Shared resources: Team accounts, cross-org integrations
Each pair operates independently with separate audit trails.
Supported Configurations and Options
Configuration | Description | Scope | Mandatory |
Client ID | Unique identifier for credential pair | Per credential | Yes |
Client Secret | Authentication token (shown once) | Per credential | Yes |
Key Name | Descriptive label for credential pair | Per credential | Yes |
Environment Tag | Dev, Staging, Production | Optional, user-defined | No |
Expiration Date | Optional credential validity period | Per credential | No (if enabled in plan) |
IP Whitelist | Restrict usage to specific IP ranges | Per credential | No (if enabled in plan) |
Scope/Permissions | Read-only, full access, specific endpoints | Per credential | No (if enabled in plan) |
Other Technical Specifications
Aspect | Details |
Credential Format | Client ID (alphanumeric) + Client Secret (long hash) |
Secret Display | Shown once at generation; no retrieval mechanism |
Storage Location | Encrypted in Docupath platform database |
Transport Security | All API requests must use HTTPS/TLS 1.2+ |
Authentication Method | OAuth 2.0 — Client ID/Secret are exchanged for a short-lived access token at |
Credential Lifetime | The credential pair is valid until manually deleted (no automatic expiration unless configured). Access tokens issued from it are short-lived and expire per |
Rotation Tracking | Activity log records all generation, deletion, and API usage events |
Multi-tenant Isolation | Credentials are tenant-specific; no cross-tenant usage |
Rate Limiting | May apply per credential pair (plan-dependent) |
Audit Trail | All API calls logged with timestamp, endpoint, and credential ID |
Notes
Secret Display Limitation: Client Secret is shown only once; if lost, the credential pair must be deleted and regenerated
No Selective Deletion: Deleting a credential immediately invalidates all requests using it; partial access revocation is not supported
No Automatic Rotation: Credentials do not auto-expire; rotation is a manual administrative task
Cross-Tenant Restrictions: Credentials are tenant-isolated and cannot be shared between organizations
Rate Limiting Scope: If rate limiting is enabled, it applies to the entire credential pair; no per-endpoint limits
Credential Reuse Risk: Using the same credential pair across multiple systems increases risk if one system is compromised; use separate pairs per system when possible
No In-place Secret Rotation: To rotate a secret, you must generate a new pair; in-place changes are not supported
Legacy Systems Integration: Older systems may not support modern authentication methods; consult the integration guide for compatibility