Skip to main content

API Overview

The EntryGuard API provides programmatic access to manage dynamic IP whitelisting for your cloud resources. This REST API allows you to create sessions, manage resources, configure credentials, and control access to your infrastructure.

Base URL​

All API requests should be made to:

https://api.entryguard.io/api/v1

Authentication​

EntryGuard supports two authentication methods:

JWT Bearer Tokens​

Use JWT tokens for user-based authentication. Include the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Obtaining Tokens

Get an access token by registering a new account or logging in:

# Register new organization and admin user
curl -X POST https://api.entryguard.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "organizationName": "Acme Corp",
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

Token Lifecycle

  • Access tokens expire after a configurable period (default: 15 minutes)
  • Refresh tokens are valid for 7 days (default)
  • Use POST /auth/refresh with your refresh token to obtain a new access token without re-authenticating
# Refresh your access token
curl -X POST https://api.entryguard.io/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "your-refresh-token-here"
  }'

API Keys​

API keys provide programmatic access for automated workflows and are available on the paid plan.

Include the API key in the X-API-Key header:

X-API-Key: egk_1a2b3c4d5e6f7g8h9i0j

Key Features

  • Scoped access control
  • No expiration (until revoked)
  • Ideal for CI/CD pipelines and automated scripts
  • Can be restricted to specific resources or operations
# Using an API key
curl -X POST https://api.entryguard.io/api/v1/sessions \
  -H "X-API-Key: egk_1a2b3c4d5e6f7g8h9i0j" \
  -H "Content-Type: application/json" \
  -d '{
    "durationHours": 2
  }'

Request Format​

All API requests must use application/json content type:

Content-Type: application/json

Example Request

curl -X POST https://api.entryguard.io/api/v1/resources \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Database",
    "provider": "AWS",
    "credentialId": "550e8400-e29b-41d4-a716-446655440000",
    "config": {
      "securityGroupId": "sg-0123456789abcdef0",
      "region": "us-east-1"
    }
  }'

Response Format​

All API responses return JSON with application/json content type.

Success Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Production Database",
  "provider": "AWS",
  "createdAt": "2024-01-15T10:30:00Z"
}

Rate Limiting​

The API enforces per-IP rate limiting to ensure fair usage and system stability.

Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642248600

Rate Limit Exceeded

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later.",
  "path": "/api/v1/sessions"
}

Default limits are configurable per deployment. Contact support to request higher rate limits.

Pagination​

Endpoints that return lists of resources support pagination using query parameters:

Parameters

  • page - Zero-based page number (default: 0)
  • size - Number of items per page (default: 20, max: 100)

Example Request

curl -X GET "https://api.entryguard.io/api/v1/audit-logs?page=0&size=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Format

Paginated responses follow Spring's Page format:

{
  "content": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "eventType": "SESSION_STARTED",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "totalElements": 150,
  "totalPages": 3,
  "number": 0,
  "size": 50,
  "first": true,
  "last": false,
  "numberOfElements": 50
}

Response Fields

  • content - Array of items for the current page
  • totalElements - Total number of items across all pages
  • totalPages - Total number of pages
  • number - Current page number (zero-based)
  • size - Requested page size
  • first - Whether this is the first page
  • last - Whether this is the last page
  • numberOfElements - Number of items in current page

Data Formats​

UUIDs​

All resource identifiers use UUID v4 format:

123e4567-e89b-12d3-a456-426614174000

Timestamps​

All timestamps are in ISO 8601 format with UTC timezone:

2024-01-15T10:30:00Z

IP Addresses​

IP addresses are represented as strings in standard notation:

{
  "ipv4": "203.0.113.42",
  "ipv6": "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
}

CIDR notation is used for IP ranges:

{
  "cidr": "203.0.113.0/24"
}

Multi-Tenancy​

All API operations are scoped to your organization. You can only access resources, users, and sessions that belong to your organization.

Organization Isolation

  • Each authenticated request is automatically scoped to your organization
  • You cannot view or modify data from other organizations
  • All resource IDs are unique across the platform, but access is enforced by organization membership

Example

If you request a resource by ID that exists but belongs to a different organization, you'll receive a 404 Not Found response:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 404,
  "error": "Not Found",
  "message": "Resource not found",
  "path": "/api/v1/resources/550e8400-e29b-41d4-a716-446655440000"
}

CORS​

The API supports Cross-Origin Resource Sharing (CORS) for web applications. Allowed origins are configured per deployment.

If you're building a web application and encountering CORS issues, ensure your domain is included in the allowed origins list.

Versioning​

The API is versioned using URL path prefixes. The current version is v1:

/api/v1/...

Future versions will be released as /api/v2/, etc. Version 1 will be supported for at least 12 months after a new version is released.

Testing​

A health check endpoint is available for monitoring and testing connectivity:

curl https://api.entryguard.io/api/v1/health

Response

{
  "status": "UP"
}

You can also detect your current IP address as seen by the API:

curl https://api.entryguard.io/api/v1/detect-ip

Response

{
  "ip": "203.0.113.42",
  "version": "IPv4"
}

Getting Help​