Ezylegal

Authentication

All ezylegal API requests require authentication using API keys. This guide covers how to authenticate requests, manage your API keys, and follow security best practices.

API Keys

API keys are used to authenticate requests to the ezylegal API. Each key is associated with your Partner account and has full access to all API endpoints.

Key Format

API keys are prefixed with ezc_ followed by a random string:

ezc_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Test vs Live Keys

ezylegal provides two types of API keys:

| Key Type | Prefix | Purpose | |----------|--------|---------| | Test | ezc_test_ | For development and testing | | Live | ezc_live_ | For production use |

Test keys work identically to live keys but:

  • Sessions created with test keys are marked as test
  • No billing is incurred for test sessions
  • Webhooks still fire normally

Authenticating Requests

Include your API key in the Authorization header using the Bearer scheme:

curl https://api.ezy-forms.com.au/v1/sessions \
  -H "Authorization: Bearer ezc_live_your_api_key_here"

JavaScript Example

const headers = {
  'Authorization': `Bearer ${process.env.EZYCOLLECT_API_KEY}`,
  'Content-Type': 'application/json',
};

const response = await fetch('https://api.ezy-forms.com.au/v1/sessions', {
  method: 'GET',
  headers,
});

Python Example

import os
import requests

headers = {
    'Authorization': f'Bearer {os.environ["EZYCOLLECT_API_KEY"]}',
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://api.ezy-forms.com.au/v1/sessions',
    headers=headers,
)

Managing API Keys

Creating a New Key

  1. Log in to your Partner Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create New Key
  4. Give your key a descriptive name (e.g., "Production Server")
  5. Copy the key immediately - it won't be shown again

Rotating Keys

To rotate your API key:

  1. Create a new API key
  2. Update your application to use the new key
  3. Verify the new key works correctly
  4. Delete the old key

Tip: Keep both keys active during the transition period to avoid downtime.

Revoking Keys

To revoke an API key:

  1. Go to Settings → API Keys
  2. Find the key you want to revoke
  3. Click the Delete button
  4. Confirm the deletion

Revoked keys immediately stop working for all requests.

Security Best Practices

Never Expose Keys in Client-Side Code

API keys should only be used in server-side code. Never include them in:

  • JavaScript running in the browser
  • Mobile app source code
  • Public repositories
  • Client-side configuration files

Use Environment Variables

Store your API key in environment variables:

# .env file (never commit this!)
EZYCOLLECT_API_KEY=ezc_live_your_key_here

// Access in your code
const apiKey = process.env.EZYCOLLECT_API_KEY;

Use Different Keys for Different Environments

Maintain separate keys for:

  • Development: Test key for local development
  • Staging: Test key for pre-production testing
  • Production: Live key for production use

Monitor Key Usage

Regularly review your API usage in the Partner Dashboard to detect unusual activity:

  • Unexpected spikes in requests
  • Requests from unknown IP addresses
  • High error rates

Rotate Keys Regularly

Rotate your API keys periodically (e.g., every 90 days) as a security best practice.

Error Responses

Missing Authentication

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

HTTP Status: 401 Unauthorized

Invalid API Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked"
  }
}

HTTP Status: 401 Unauthorized

Insufficient Permissions

{
  "error": {
    "code": "forbidden",
    "message": "This API key does not have permission to access this resource"
  }
}

HTTP Status: 403 Forbidden

Next Steps