Authorization

Beta

The Leadpush Developer API uses API Key authentication to secure all endpoints. This guide will walk you through generating API keys and implementing authentication with your applications.

Overview

Understanding API authentication and security best practices.

Authentication Method

Leadpush uses Bearer Token Authentication with API Keys. All API requests must include a valid API Key in the Authorization header.

Security Features

  • Scoped Access: API Keys can be configured with specific permissions
  • Rate Limiting: Each key has built-in rate limiting for security
  • Audit Logging: All API key usage is tracked and logged
  • Expiration: Keys can be set to expire automatically

Base URL

All API Requests should be made to:

GET https://api.leadpush.io/v1 HTTP/1.1

Generating Developer Keys

Step-by-step guide to create and configure your API keys.

Follow these steps to generate a new API Key for your application:

  1. Navigate to your workspace settings.
  2. Click on the Developer Keys Tab.
    Create Api Key
  3. In the top right corner, click on the + Api Key button.
  4. A modal will appear with options to configure your API Key. Click on Create.
  5. After creating your api key, a new window will appear with your API Key. Copy the API Key and save it somewhere safe.
Important: API Keys are only visible once and cannot be retrieved again. Copy and store your key in a secure location immediately.

API Key Management

Once created, you can manage your API keys through the Developer Keys interface:

  • View Usage: Monitor request counts and rate limit status
  • Revoke Keys: Immediately disable compromised or unused keys
  • Update Permissions: Modify key access levels (requires regeneration)
  • Monitor Activity: View recent API requests and responses

Implementing Authentication

How to use your API Key to authenticate requests to the Leadpush API.

Request Headers

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

GET https://api.leadpush.io/v1 HTTP/1.1

Authorization: Bearer <YOUR_API_KEY_HERE> 
Content-Type: application/json

Error Handling

Understanding and handling authentication errors.

Common Authentication Errors

Status CodeErrorDescriptionSolution
401UnauthorizedMissing or invalid API keyCheck your API key and header format
403ForbiddenKey lacks required permissionsUpdate key permissions or use different key
429Too Many RequestsRate limit exceededImplement exponential backoff
500Internal Server ErrorServer-side authentication issueContact support

Error Response Format

{ 
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key provided",
    "details": "The API key is either missing, invalid, or has been revoked"
  }
}

Best Practices for Error Handling

  • Always check response status codes
  • Implement proper retry logic for temporary failures
  • Log authentication errors for debugging
  • Never expose API keys in error messages

Security Best Practices

Keep your API keys secure and your integration safe.

Protecting Your API Keys

Never commit API keys to version control or expose them in client-side code.

Do:

  • Store keys in environment variables
  • Use secure key management services
  • Rotate keys regularly
  • Monitor key usage for anomalies
  • Use the minimum required permissions

Don't:

  • Hard-code keys in your application
  • Share keys between environments
  • Use keys with excessive permissions
  • Ignore suspicious activity alerts