Skip to main content

Authentication

All Debitura API requests require authentication using API keys.

API Keys​

Debitura uses API key authentication with bearer tokens.

Obtaining API Keys​

Sandbox keys:

  • Request through your account manager
  • Available immediately after onboarding
  • Used for development and testing

Production keys:

  • Provided after compliance verification
  • Requires signed agreement
  • Used for live integrations

Key Format​

API keys are long alphanumeric strings that look like:

deb_live_abc123def456ghi789jkl012mno345pqr678

Keys have different prefixes based on environment:

  • Sandbox: deb_test_...
  • Production: deb_live_...

Making Authenticated Requests​

Include your API key in the Authorization header of every request:

curl https://api.debitura.com/v1/cases \
  -H "Authorization: Bearer deb_live_abc123def456ghi789jkl012mno345pqr678" \
  -H "Content-Type: application/json"

Request Headers​

Every authenticated request should include:

HeaderValueRequired
AuthorizationBearer {your_api_key}Yes
Content-Typeapplication/jsonYes
Idempotency-KeyUnique request IDRecommended

Security Best Practices​

Protecting Your API Keys​

Never expose API keys
  • Never commit keys to version control
  • Never share keys in support tickets
  • Never log keys in application logs
  • Never expose keys in client-side code

Do:

  • Store keys in environment variables
  • Use secret management systems
  • Rotate keys periodically
  • Use different keys per environment
  • Restrict key permissions when possible

Don't:

  • Hardcode keys in source code
  • Share keys via email or chat
  • Use production keys in development
  • Commit .env files to git

Key Rotation​

Rotate your API keys regularly:

  1. Generate new API key via portal or support
  2. Update your application configuration
  3. Deploy changes
  4. Verify new key works
  5. Revoke old key
tip

Keep the old key active for a transition period to avoid downtime during deployment.

Error Handling​

Common Authentication Errors​

401 Unauthorized

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided"
  }
}

Causes:

  • Missing Authorization header
  • Invalid or expired API key
  • Malformed bearer token
  • Wrong environment key (sandbox vs production)

403 Forbidden

{
  "error": {
    "type": "permission_error",
    "message": "Your API key does not have permission to perform this action"
  }
}

Causes:

  • API key lacks required permissions
  • Resource belongs to different account
  • Feature not enabled for your account

Testing Authentication​

Test your authentication setup:

# Test sandbox authentication
curl https://api.sandbox.debitura.com/v1/auth/test \
  -H "Authorization: Bearer deb_test_your_key_here"

# Expected response
{
  "authenticated": true,
  "environment": "sandbox",
  "account_id": "acc_123456",
  "permissions": ["cases.read", "cases.write", "payments.read"]
}

Next Steps​

Once authenticated, you can: