Why does my OAuth token keep failing with "invalid_client"?

Check for trailing spaces in your client ID/secret. Signicat's dashboard has a copy button that sometimes grabs extra whitespace. Also, if you just created the API client, wait 10-15 minutes - there's propagation delay that isn't documented. ```bash # This fails silently with trailing space CLIENT_ID="abc123 " # This works CLIENT_ID="abc123" ``` Also make sure your domain is actually verified. "Domain verification pending" means your tokens won't work even though they're generated.

Why can't I execute workflows with my API client?

You probably chose "Flow Viewer" role instead of "Flow Editor" when creating the client. Flow Viewer is read-only - can't execute shit. Delete the client and create a new one with Flow Editor role. There's no way to upgrade permissions on existing clients. Learned this the hard way after spending 2 hours debugging "permission denied" errors.

How do I know when a workflow actually finishes?

You don't. There are no webhooks - you have to poll the status endpoint every 30 seconds like it's 2005. European eID workflows can take 5-30 seconds depending on which provider and whether the user is on mobile. ```javascript // Poll every 30 seconds until finished or you give up async function waitForCompletion(instanceId) { let attempts = 0; while (attempts < 60) { // 30 minutes max const status = await checkStatus(instanceId); if (['Finished', 'Faulted', 'Cancelled'].includes(status)) { return status; } await sleep(30000); attempts++; } throw new Error('Workflow timeout - probably suspended'); } ```

What does "Suspended" status actually mean?

The workflow is waiting for the user to do something - usually BankID authentication or document signing. You can't programmatically resume it - the user has to complete their part first. The API doesn't tell you what specific step is suspended. You have to guess from the workflow design or check the execution logs (which are sometimes helpful, sometimes not).

Can I test European eID methods in sandbox?

Nope. BankID, MitID, and most other European eID methods don't work in sandbox. You get fake success responses with dummy data. Have to test with real accounts in production, which is terrifying for financial applications. Some identity providers have their own test environments, but you need separate agreements with each one.

Why does Swedish BankID randomly fail?

Swedish BankID randomly fails because it goes down for maintenance every few months. Usually weekends, no advance notice, and the error messages are about as helpful as a chocolate teapot. Danish MitID has similar issues - I've seen it go down during business hours on a Tuesday. The October incident last year taught us to always check [Signicat's status page](https://status.signicat.com/) first. Budget for 95% uptime, not the 99.9% they claim in their marketing.

How much does this actually cost?

They don't publish pricing because it's "call for enterprise quote" territory. Expect €5k-10k/month minimum, scaling up to €50k+/month for high volume. Plus €10k-25k setup fees. If you're doing less than 1000 European identity verifications per month, DocuSign is probably cheaper.

Can I export workflows from Mint Builder?

No. Workflows are locked into their platform. No export, no backup, no migration path. Classic vendor lock-in. If you switch providers, you're rebuilding everything from scratch.

Why is latency so high from the US?

European data residency requirements mean servers are in EU. Expect 150-200ms base latency from US East Coast, 250ms+ from West Coast. Factor this into your UX - European eID workflows already take 10-30 seconds.

What happens when Signicat's API goes down?

You're fucked until it comes back. No redundancy options, no failover. The [status page](https://status.signicat.com/) will eventually acknowledge the outage. European business hours support means overnight outages in the US get zero response until morning CET.

Do I actually need professional services for integration?

Depends. Basic API integration is straightforward if you're comfortable with OAuth 2.0 and polling. You'll want professional services if: - Complex workflow requirements (multi-step approvals, conditional logic) - Enterprise SSO integration requirements - Regulatory compliance validation (they know eIDAS better than you) - Timeline pressure (their engineers are competent, will save you debugging time)

Is there any alternative to Signicat for European eID?

Not really, that's why they can charge enterprise prices. [Veriff](https://www.veriff.com/) covers some European methods but not BankID/MitID. You could integrate directly with each country's eID system, but that's 6-12 months of work per country plus ongoing maintenance hell. For most use cases, you're paying the Signicat tax or building it yourself.

Currently viewing the AI version

Switch to human version

Signicat Mint API: AI-Optimized Technical Reference

Configuration

OAuth 2.0 Setup

Role Requirement: Must use "Flow Editor" role (not "Flow Viewer") to execute workflows
Domain Verification: Required, adds 24-48 hours to setup
Token Expiry: 3600 seconds, implement refresh mechanism
Propagation Delay: 10-15 minutes after client creation before tokens work

Working Authentication Implementation

async function getAccessToken() {
  const response = await fetch('https://api.signicat.com/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.SIGNICAT_CLIENT_ID,
      client_secret: process.env.SIGNICAT_CLIENT_SECRET
    })
  });
  
  if (!response.ok) {
    throw new Error(`Auth failed: ${response.status} ${response.statusText}`);
  }
  
  const { access_token, expires_in } = await response.json();
  return { token: access_token, expiresIn: expires_in };
}

Common Authentication Failures

invalid_client: Wrong client ID/secret or trailing whitespace
unauthorized_client: Domain verification pending
access_denied: Wrong role permissions (need Flow Editor)

European eID Integration

Supported Methods

Coverage: 35+ European identity systems
Key Methods: BankID (Norway/Sweden), MitID (Denmark), itsme (Belgium), eIDAS nodes
Geographic Focus: Europe-only, no global coverage

Implementation Reality

BankID Integration: Direct integration takes weeks, complex Norwegian documentation
Sandbox Limitations: European eID methods don't work in sandbox environment
Testing Requirements: Must test with real accounts in production
Maintenance Windows: Swedish BankID fails regularly (monthly maintenance), Danish MitID has weekend outages

Performance Characteristics

Response Times: 5-30 seconds for eID verification depending on provider
Reliability: Budget for 95% uptime (not the claimed 99.9%)
Geographic Latency: 150-200ms from US East Coast, 250ms+ from West Coast

API Operations

Workflow Execution

# Start workflow
POST /flows/{id}/execute
Authorization: Bearer {token}
{
  "input": {
    "email": "user@example.com",
    "product": "premium_account"
  }
}

Status Monitoring (Polling Required)

No Webhooks: Must poll status endpoint every 30 seconds
Status Values:
- Running: Processing
- Suspended: Waiting for user input (common, cannot be resumed programmatically)
- Finished: Completed successfully
- Faulted: Failed with error
- Cancelled: User abandoned

Status Polling Implementation

async function waitForCompletion(instanceId) {
  let attempts = 0;
  while (attempts < 60) { // 30 minutes max
    const status = await checkStatus(instanceId);
    if (['Finished', 'Faulted', 'Cancelled'].includes(status)) {
      return status;
    }
    await sleep(30000);
    attempts++;
  }
  throw new Error('Workflow timeout - probably suspended');
}

File Management

Download Implementation

const downloadUrl = `https://api.signicat.com/flows/instances/${instanceId}/files/${referenceId}/download`;
const response = await fetch(downloadUrl, {
  headers: { 'Authorization': `Bearer ${token}` }
});
const buffer = await response.buffer();

File Handling Issues

Large Files: Files >10MB frequently timeout, implement retry with exponential backoff
Expiration: Files expire after 30 days (not clearly documented)
Multi-Document: ZIP files for multiple documents come as single download
No Progress Tracking: No progress indication for large downloads

Performance and Scaling

API Rate Limits

Undocumented Limits: Approximately 100 requests/minute
HTTP 429: Rate limit exceeded response
No Batch Operations: Must poll workflows individually

Latency Characteristics

Flow Execution: <500ms to get instance ID
Status Checks: 100-200ms
File Downloads: 2-10 seconds for normal PDFs
European eID: 5-30 seconds depending on provider

Scaling Limitations

No Webhooks: Polling-only architecture limits scalability
Concurrent Workflows: Performance degrades with 100+ concurrent workflows
European Business Hours: Load issues during peak EU hours

Cost Analysis

Component	Cost Range	Break-Even Point
Monthly License	€5k-50k+ (volume-based)	1000+ European verifications/month
Setup Fees	€10k-25k	One-time
Professional Services	€500-1500/day	Complex workflows only
Minimum Commitment	€5k-10k/month	Enterprise contracts

Hidden Costs

Domain verification process delays
European-hours support only
No export/migration capability (vendor lock-in)
Separate testing environment setup

Critical Warnings

Production Deployment Issues

European Data Residency: All servers in EU, impacts US latency
Support Timezone: European business hours only (CET)
Vendor Lock-in: No workflow export capability
No Failover: Single point of failure during outages

Testing Limitations

Sandbox Restrictions: Most European eID methods return dummy data
Separate Accounts: Sandbox and production require separate setups
Real Account Testing: Must use production for actual eID testing

Common Failure Scenarios

HTTP 503: European identity providers down (BankID maintenance)
HTTP 422: Workflow validation failed (missing required inputs)
Suspended Workflows: User abandonment during eID process
Token Expiration: 401 errors after 1 hour without refresh

Decision Criteria

Use Signicat When:

European Operations: Need BankID, MitID, or other European eID methods
Complex Workflows: Multi-step identity verification beyond simple signing
Regulatory Compliance: Financial services, healthcare, regulated industries
Business User Control: Want non-technical users to modify workflows
Volume Threshold: 1000+ European verifications monthly

Don't Use Signicat When:

Simple E-signatures: DocuSign is cheaper and more straightforward
US-Only Operations: Limited value outside Europe
Developer Control: Want full programmatic control over workflows
Cost Sensitivity: Small projects under 1000 verifications/month
Real-time Requirements: Polling-only architecture inadequate

Alternative Comparison

DocuSign: Better for simple signing, US-focused, has webhooks
OneSpan: Better for banking/finance, complex setup
Build In-House: 6-12 months development, €200k+ cost, ongoing maintenance
Direct eID Integration: €50k+ per country, maintenance nightmare

Implementation Patterns

CRM Integration Pattern

async function onLeadConversion(leadId, contactInfo) {
  const instance = await executeWorkflow('identity-verification-flow', {
    email: contactInfo.email,
    phone: contactInfo.phone,
    crmLeadId: leadId
  });
  
  await db.updateLead(leadId, { 
    verificationInstanceId: instance.id,
    status: 'verification_started'
  });
}

Background Polling Pattern

async function pollWorkflowStatus() {
  const pending = await db.getPendingVerifications();
  
  for (const record of pending) {
    const status = await getWorkflowStatus(record.instanceId);
    
    if (status === 'Finished') {
      const documents = await downloadWorkflowFiles(record.instanceId);
      await processCompletedVerification(record.crmLeadId, documents);
    }
  }
}

Error Recovery

Download Retry Implementation

async function downloadWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, { timeout: 60000 });
      if (response.ok) return await response.buffer();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000); // Exponential backoff
    }
  }
}