# Welcome Welcome to the IPAware Console documentation! This guide will help you navigate and utilize all features of the IPAware platform. ### What is IPAware Console? The IPAware Console is a comprehensive web-based dashboard that allows you to: * [**Manage API Keys** ](/dashboard/markdown)- Create and control authentication credentials for your applications * [**Monitor Usage**](#usage-analytics) - Track your API request metrics and quota consumption * [**Manage Teams**](/dashboard/images-and-media) - Invite members and control access with role-based permissions * [**Configure Security**](#security-features) - Set up 2FA, passkeys, and manage active sessions * [**Control IP Whitelist** ](/dashboard/integrations)- Specify which IP addresses can access your API * [**Handle Billing**](/dashboard/billing) - Manage subscriptions and view payment history * [**Analyze IPs**](/dashboard/whois-lookup) - Use the built-in WHOIS tool for IP intelligence lookups ### Getting Started New to IPAware? Start with these guides: 1. [**Authentication** ](/getting-started/quickstart)- Learn how to sign in and create your account 2. [**Dashboard Overview**](/dashboard/editor) - Understand your main dashboard 3. [**API Keys**](/dashboard/markdown) - Create your first API key 4. [**Team Management** ](/dashboard/images-and-media)- Invite team members ### Key Features #### πŸ” Multiple Authentication Methods * Traditional email/password login * Passwordless magic link authentication * WebAuthn passkey support * Two-factor authentication (2FA) #### πŸ‘₯ Team Collaboration * Invite unlimited team members * Custom role-based access control * Granular permission management * Organization ownership transfer #### πŸ“Š Usage Analytics * Real-time request monitoring * Monthly usage history * Success rate tracking * Quota management #### πŸ›‘οΈ Security Features * Two-factor authentication (TOTP) * Hardware security keys (passkeys) * Session management * IP whitelisting #### πŸ’³ Flexible Billing * Multiple subscription tiers * Monthly and annual billing * Stripe-powered payments * Self-service plan changes ### Navigation Use the sidebar to navigate through different sections: * [**Authentication**](/getting-started/quickstart) - Sign in, registration, and password management * **Dashboard** - Main console features and tools * [Overview](/dashboard/editor) * [API Keys](/dashboard/markdown) * [Team](/dashboard/images-and-media) * [Roles & Permissions](/dashboard/interactive-blocks) * [Whitelist](/dashboard/integrations) * [Settings](/dashboard/settings) * [Billing](/dashboard/billing) * [WHOIS Lookup](/dashboard/whois-lookup) ### Support Need help? Contact us at ### Quick Links * [API Documentation](https://api-docs.ipaware.io/) * [Changelog](https://ipaware.com/changelog) # Summary ### Getting Started * [Introduction](/) * [Authentication](/getting-started/quickstart) * Creating an Account * Sign In Methods * Password Reset * Two-Factor Authentication ### Dashboard * [Overview](/dashboard/editor) * Quick Stats * Monthly Activity * Navigation * [API Keys](/dashboard/markdown) * Creating API Keys * Managing Keys * Key Rotation * Security Best Practices * [Team Management](/dashboard/images-and-media) * Inviting Members * Managing Roles * Ownership Transfer * Organization Details * [Roles & Permissions](/dashboard/interactive-blocks) * System Roles * Custom Roles * Permission Groups * Best Practices * [IP Whitelist](/dashboard/integrations) * Adding IP Addresses * Managing Whitelist * Whitelist Limits * Troubleshooting * [Settings](/dashboard/settings) * Account Security * Two-Factor Authentication * Passkeys * Session Management * Account Deletion * [Billing & Subscriptions](/dashboard/billing) * Subscription Plans * Upgrading Your Plan * Managing Subscriptions * Payment Methods * Invoices * [WHOIS Lookup](/dashboard/whois-lookup) * Performing a Lookup * Understanding Results * Use Cases * Best Practices # Authentication Learn how to access your IPAware Console account using multiple authentication methods. ### Creating an Account #### Standard Registration **Steps:** 1. **Start Registration** * Click **Start Free Trial** on the [login page](https://console.ipaware.io/) * Enter your email address * Complete the Cloudflare Turnstile verification * Click **Send verification code** 2. **Verify Email** * Check your email for a 6-digit verification code * Enter the code in the console * Click **Verify** * If you don't receive the code, click **Resend** (available after 60 seconds) 3. **Set Password** * Create a strong password (minimum 8 characters) * Confirm your password * Click **Create account** 4. **Welcome!** * Your account is created * You'll be redirected to the dashboard * A new organization is automatically created for you #### Invitation-Based Registration If you've been invited to join an existing organization: **Steps:** 1. **Click Invitation Link** * Open the email invitation * Click the invitation link * You'll be taken to the registration page with your email pre-filled 2. **Set Password** * Create a password for your account * Confirm the password * Click **Create account** 3. **Join Organization** * You'll automatically join the organization * Your role will be assigned based on the invitation > **Note:** Invitation links expire after a certain period. Contact the organization owner if your link has expired. *** ### Sign In Methods IPAware supports three different ways to sign in to your account: #### 1. Email & Password The traditional authentication method. **Steps:** 1. Navigate to the [login page](https://console.ipaware.com) 2. Enter your email address 3. Enter your password 4. Complete the Cloudflare Turnstile verification 5. Click **Sign In** > **Note:** If you have 2FA enabled, you'll be prompted to enter your authenticator code after signing in. #### 2. Magic Link (Passwordless) Sign in without remembering a password - we'll email you a secure link. **Steps:** 1. On the login page, click **Use Magic Link instead** 2. Enter your email address 3. Complete the Cloudflare Turnstile verification 4. Click **Send Magic Link** 5. Check your email inbox 6. Click the link in the email to sign in automatically > **Security:** Magic links expire after a short period and can only be used once. #### 3. Passkey (WebAuthn) Use biometric authentication or hardware security keys for the most secure login experience. **Steps:** 1. On the login page, click **Sign in with a Passkey** 2. Your browser will prompt you to select a passkey 3. Authenticate using your device (fingerprint, Face ID, security key, etc.) 4. You'll be signed in automatically > **Requirements:** Passkeys must be registered first from the Settings page after signing in with another method. *** ### Password Reset Forgot your password? Reset it easily: **Steps:** 1. **Request Reset** * Click **Forgot?** next to the password field on the login page * Enter your email address * Complete the Cloudflare Turnstile verification * Click **Send Reset Link** 2. **Check Email** * Look for an email with the subject "Password Reset Request" * Click the reset link in the email 3. **Set New Password** * Enter your new password (minimum 8 characters) * Confirm the new password * Click **Update Password** 4. **Sign In** * You'll be redirected to the login page * Sign in with your new password > **Security:** Reset links expire after 1 hour for security purposes. *** ### Email Verification #### Verifying a New Email Address When you change your email address in Settings: 1. **Verification Email Sent** * A verification link is sent to your new email address * A notification is sent to your old email address 2. **Click Verification Link** * Open the email sent to your new address * Click the verification link 3. **Email Updated** * Your email is now updated * You'll be signed out and need to sign in with the new email #### Reverting an Email Change If you didn't request the email change or made a mistake during it: 1. **Open Revert Email** * Check the notification sent to your old email * Click **Revert this change** 2. **Email Restored** * Your email is restored to the original address * The unauthorized change is cancelled *** ### Two-Factor Authentication (2FA) If 2FA is enabled on your account, you'll need to provide an additional code after entering your password. **During Login:** 1. Enter your email and password 2. Click **Sign In** 3. You'll be prompted for a 2FA code 4. Open your authenticator app (Google Authenticator, Authy, etc.) 5. Enter the 6-digit code 6. Click **Verify** **Using Recovery Code:** If you don't have access to your authenticator app: 7. On the 2FA screen, click **Use Recovery Code** 8. Enter one of your recovery codes 9. Click **Verify** > **Important:** Each recovery code can only be used once. Store them securely! *** ### Security Best Practices #### Password Guidelines * Use at least 12 characters * Include uppercase and lowercase letters * Include numbers and special characters * Don't reuse passwords from other services * Use a password manager #### Account Security * Enable 2FA for additional security * Register a passkey for passwordless authentication * Review active sessions regularly * Use magic links on trusted devices only * Never share your password or recovery codes #### Session Management * Sign out when using shared computers * Review and revoke unknown sessions from Settings * Each session shows device, location, and last activity *** ### Troubleshooting #### Can't Sign In **Check these common issues:** * **Incorrect password:** Use the password reset feature * **Email not verified:** Check your inbox for verification email * **Account suspended:** Contact support at * **2FA code not working:** Ensure your device time is synchronized #### Not Receiving Emails **Try these solutions:** * Check your spam/junk folder * Verify the email address is correct * Wait a few minutes - emails can be delayed * Try resending the email * Contact support if issues persist #### Passkey Not Working **Common fixes:** * Ensure your browser supports WebAuthn * Check that your device/security key is properly connected * Try a different passkey if you have multiple registered * Clear browser cache and try again *** ### Next Steps After signing in: * Set up your first API key * Invite team members * Configure security settings * Review your usage # Overview The Overview tab is your command center for monitoring API usage, tracking performance, and understanding your account status. ### Quick Stats The dashboard displays four key metrics at the top: #### Monthly Requests * **What it shows:** Total API requests made in the current billing period * **Trend indicator:** Shows percentage change compared to last month * ↑ Green = Increase * ↓ Red = Decrease * β†’ Gray = No change * **Use case:** Monitor your API usage patterns and growth #### Remaining Quota * **What it shows:** Number of requests remaining in your current plan * **Display:** Shows actual number or ♾️ for unlimited plans * **Alert:** Keep an eye on this to avoid hitting your limit * **Action:** Upgrade your plan if you're consistently hitting limits #### Success Rate * **What it shows:** Percentage of successful API requests * **Calculation:** (Successful requests / Total requests) Γ— 100 * **Healthy range:** 95% or higher is excellent * **Status indicator:** "Operational" when performing well * **Troubleshooting:** Low success rate may indicate API key issues or invalid requests #### Whitelist Limit * **What it shows:** Percentage of IP whitelist slots used * **Details:** Shows "X / Y IPs used" (e.g., "3 / 50 IPs used") * **Plan-based:** Limit varies by subscription tier * **Action:** Remove unused IPs or upgrade for more slots *** ### Current Plan Located in the top-right corner of the dashboard: * **Plan Badge:** Displays your current subscription tier * Free Tier * Pro Monthly * Pro Yearly * Custom plans *** ### Monthly Activity Table Detailed breakdown of your API usage over the last 12 months. #### Columns Explained | Column | Description | | ------------------ | ---------------------------------------------- | | **Period** | Month and year (e.g., "January 2026") | | **Total Requests** | All API calls made in that month | | **Success** | Number of successful requests (2xx responses) | | **Failure** | Number of failed requests (4xx, 5xx responses) | | **Status** | Success rate badge with percentage | #### Understanding the Data **Success Rate Badge Colors:** * 🟒 **Green (95-100%):** Excellent performance * 🟑 **Yellow (80-94%):** Good, but room for improvement * πŸ”΄ **Red (<80%):** Needs attention **Common Patterns:** * **Steady growth:** Increasing requests month-over-month * **Seasonal spikes:** Higher usage during specific months * **Sudden drops:** May indicate integration issues or service changes *** ### Navigation Use the sidebar to access different sections: #### Console Sections * **Overview** (current page) - Usage statistics and metrics * **API Keys** - Manage authentication credentials * **Team** - Invite and manage organization members * **Roles** - Configure custom permissions * **Whitelist** - Control IP access * **Settings** - Account security and preferences * **Billing** - Subscription and payment management * **Whois Lookup** - IP intelligence tool #### Additional Links * **Logout** - Sign out of your account *** ### Understanding Your Usage #### Billing Period Your usage metrics are calculated based on your billing cycle: * **Free Tier:** Calendar month (resets on the 1st) * **Paid Plans:** Subscription period (e.g., from signup date) #### Quota Management **When approaching your limit:** 1. **Monitor regularly:** Check the "Remaining Quota" card 2. **Optimize usage:** Review which endpoints consume most requests 3. **Consider upgrading:** Switch to a higher tier if needed 4. **Whitelist optimization:** Remove unused IP addresses **What happens when quota is exceeded:** * API requests will be blocked #### Success Rate Optimization **If your success rate is low:** 1. **Check API keys:** Ensure they're active and have correct permissions 2. **Review request format:** Validate request parameters 3. **Check IP whitelist:** Ensure your IPs are whitelisted if required 4. **Monitor error codes:** Use logs to identify specific issues 5. **Contact support:** If issues persist *** ### Best Practices #### Regular Monitoring * **Daily:** Quick glance at success rate * **Weekly:** Review request trends * **Monthly:** Analyze full activity table before billing cycle ends #### Proactive Management * **Plan ahead:** Upgrade before hitting limits * **Clean up:** Remove unused API keys and whitelisted IPs #### Team Collaboration * **Assign roles:** Give team members appropriate access levels * **Review together:** Monthly usage reviews help optimize costs *** ### Quick Actions From the Overview page, you can quickly: 1. **Navigate to any section** - Use the sidebar menu 2. **Monitor trends** - Review the monthly activity table 3. **Assess health** - Glance at the four stat cards *** ### Next Steps * Create an API Key to start making requests * Set up IP Whitelist for additional security * Invite team members to collaborate * Configure billing to upgrade your plan # API Keys API Keys are the credentials your applications use to authenticate with the IPAware API. This guide covers everything you need to know about creating and managing API keys. ### Overview Each API key consists of: * **Key ID:** Public identifier (e.g., `key_abc123...`) - safe to log * **Secret Key:** Private credential - shown only once during creation * **Name:** Descriptive label for identification * **Role:** Determines permissions and access levels * **Status:** Active or revoked *** ### Creating an API Key **Steps:** 1. **Open Creation Modal** * Navigate to the **API Keys** tab * Click **+ Create New Key** 2. **Configure Key** * **Key Name:** Enter a descriptive name (e.g., "Production Server", "Mobile App") * **Role:** Select the appropriate role from the dropdown * Choose based on the principle of least privilege 3. **Create Key** * Click **Create** * The system generates your key immediately 4. **Save Secret Key** * **IMPORTANT:** The secret key is shown only once * Copy the secret key immediately * Store it securely (password manager, environment variables, secrets manager) * The Key ID is also displayed for reference 5. **Confirm** * Click **I have copied it** to close the modal * Your new key appears in the API Keys table > **Security Warning:** Never commit secret keys to version control or share them publicly! *** ### Managing API Keys #### Viewing API Keys The API Keys table displays: | Column | Description | | ----------- | -------------------------------------- | | **Name** | Your descriptive label | | **Key ID** | Public identifier (starts with `key_`) | | **Role** | Assigned permission role | | **Created** | Date the key was created | | **Status** | Active (green badge) | | **Actions** | Edit and Revoke buttons | #### Editing an API Key You can update the name and role of existing keys: **Steps:** 1. Click **Edit** next to the key you want to modify 2. Update the **Key Name** (optional) 3. Change the **Role** (optional) 4. Click **Save Changes** > **Note:** You cannot change the Key ID or retrieve the secret key after creation. #### Revoking an API Key Permanently disable a key to prevent further API access: **Steps:** 1. Click **Revoke** next to the key 2. Read the warning: "Applications using this key will stop working" 3. Click **Revoke Key** to confirm **Effects:** * Key is immediately deactivated * All API requests using this key will fail * Key is removed from the table * Action cannot be undone > **Use Case:** Revoke keys when rotating credentials, removing integrations, or if a key is compromised. *** ### API Key Roles Roles determine what actions an API key can perform. #### Custom Roles ### Organizations can create custom roles with specific permissions. See [Roles & Permissions](/dashboard/interactive-blocks) for details. ### Using API Keys #### Authentication Include your API key in requests using the `Authorization` header. #### Best Practices **Security:** * Store keys in environment variables, not in code * Use different keys for different environments (dev, staging, production) * Rotate keys regularly (every 90 days recommended) * Revoke unused keys immediately * Never log or display secret keys **Organization:** * Use descriptive names (include environment and purpose) * Document which key is used where * Assign minimal necessary permissions * Review keys quarterly **Monitoring:** * Track which keys are actively used * Monitor for unusual activity * Set up alerts for failed authentication attempts *** ### Key Rotation Regularly rotating API keys improves security: **Rotation Process:** 1. **Create new key** * Generate a new API key with the same role * Name it clearly (e.g., "Production Server v2") 2. **Update applications** * Deploy the new key to your applications * Test thoroughly before proceeding 3. **Monitor transition** * Ensure all services are using the new key * Check for any authentication errors 4. **Revoke old key** * Once confirmed, revoke the old key * Document the rotation in your change log **Recommended Schedule:** * Production keys: Every 90 days * Development keys: Every 180 days * Compromised keys: Immediately *** ### Troubleshooting #### "Invalid API Key" Error **Possible causes:** * Key was revoked * Incorrect secret key (typo or truncation) * Key doesn't have required permissions * IP not whitelisted (if whitelist is enabled) **Solutions:** 1. Verify the secret key is correct and complete 2. Check if key appears in the API Keys table 3. Confirm the key's role has necessary permissions 4. Ensure your IP is whitelisted #### Key Not Working After Creation **Check:** * Secret key was copied correctly (no extra spaces) * Using the secret key, not the Key ID * Authorization header is formatted correctly * API endpoint URL is correct #### Can't Create More Keys **Reason:** Some plans have limits on the number of active API keys **Solutions:** * Revoke unused keys * Upgrade your plan for higher limits * Consolidate applications to use fewer keys *** ### Security Considerations #### Key Compromise If you suspect a key has been compromised: 1. **Revoke immediately** - Don't wait 2. **Create replacement** - Generate a new key 3. **Update applications** - Deploy the new key 4. **Investigate** - Determine how the compromise occurred 5. **Review logs** - Check for unauthorized access 6. **Notify team** - Inform relevant stakeholders #### Storage Recommendations **Good Practices:** * Environment variables * Secrets management services (AWS Secrets Manager, HashiCorp Vault) * Encrypted configuration files * Password managers (for manual testing) **Bad Practices:** * ❌ Hardcoded in source code * ❌ Committed to Git repositories * ❌ Stored in plain text files * ❌ Shared via email or chat * ❌ Logged in application logs *** ### Permissions Required To manage API keys, you need these permissions: * **Create keys:** `api.key.create` * **Edit keys:** `api.key.update` * **Revoke keys:** `api.key.delete` * **View keys:** `api.key.view` *** ### Next Steps * Assign roles to keys for granular permissions * Set up IP whitelist for additional security * Monitor usage to track API consumption * Invite team members to collaborate on API management # Team Collaborate with your team by inviting members to your organization and managing their access levels. ### Overview The Team tab allows you to: * Invite new members via email * Assign and manage roles * View member status and activity * Transfer organization ownership * Update organization details * Remove members *** ### Inviting Team Members **Steps:** 1. **Open Invitation Modal** * Navigate to the **Team** tab * Click **+ Invite Member** 2. **Enter Details** * **Email:** Enter the team member's email address * **Role:** Select their initial role from the dropdown * You can change this later 3. **Send Invitation** * Click **Send Invite** * An invitation email is sent immediately 4. **Track Status** * Invited users appear in the table with "Pending" status * They have 7 days to accept the invitation **Invitation Email Contains:** * Link to create an account * Organization name * Assigned role * Expiration notice *** ### Managing Team Members #### Team Table The table displays all members and pending invitations: | Column | Description | | ----------- | ------------------------------------------------ | | **Email** | Member's email address | | **Roles** | Assigned role badges (can have multiple) | | **Status** | ACTIVE or PENDING | | **Joined** | Date they joined the organization | | **Actions** | Manage Roles, Transfer Ownership, Remove buttons | #### Member Statuses **ACTIVE** (Green Badge) * Member has accepted invitation * Has full access based on assigned roles * Can use the console and API **PENDING** (Yellow Badge) * Invitation sent but not yet accepted * Shows "(Invited)" instead of roles * Has Resend and Revoke options *** ### Managing Roles #### Assigning Roles Give members additional responsibilities: **Steps:** 1. Click **Manage Roles** next to the member 2. View their current roles in the modal 3. Select a new role from the dropdown 4. Click **Assign** 5. The role is added immediately > **Note:** Members can have multiple roles. Their effective permissions are the union of all assigned roles. #### Revoking Roles Remove specific roles from a member: **Steps:** 1. Click **Manage Roles** next to the member 2. Find the role you want to remove 3. Click **Revoke** next to that role 4. Confirm the action 5. The role is removed immediately **Effects:** * Member loses permissions associated with that role * Other roles remain active * Member is notified of the change *** ### Invitation Management #### Resending Invitations If a team member didn't receive the invitation: **Steps:** 1. Find the pending invitation in the table 2. Click **Resend** 3. A new invitation email is sent 4. The expiration timer resets #### Revoking Invitations Cancel a pending invitation: **Steps:** 1. Find the pending invitation 2. Click **Revoke** 3. Confirm the action **Effects:** * Invitation link becomes invalid * User cannot join using that link * Entry is removed from the table *** ### Removing Members Permanently remove a member from your organization: **Steps:** 1. Click **Remove** next to the member 2. Read the warning 3. Click **Remove** to confirm **Effects:** * Member loses all access immediately * Their API keys are deactivated * They're signed out of active sessions * Cannot be undone (must re-invite) > **Important:** You cannot remove yourself. Use the ownership transfer feature and delete your account if you want to leave. *** ### Organization Ownership #### Transferring Ownership Transfer full control of the organization to another member: **Requirements:** * You must be the current owner * Target member must have ACTIVE status * You must verify with your password **Steps:** 1. Click **Transfer Ownership** next to the target member 2. Read the warning carefully: * You will be demoted to Admin * The new owner has full control * This action cannot be undone 3. Enter your password to confirm 4. Click **Transfer Ownership** **What Happens:** * Target member becomes Organization Owner * You become an Admin * Page reloads to reflect changes > **Use Case:** When leaving the company, changing leadership, or restructuring the organization. *** ### Organization Details #### Viewing Details Organization information is displayed at the top of the Team tab: * Organization name * Current plan * Member count #### Editing Organization Details Update your organization's billing and contact information: **Requirements:** * `organization.update` permission **Steps:** 1. Click **Edit Details** (visible only if you have permission) 2. Update any of these fields: * **Name:** Organization display name * **Website:** Company website URL * **Address:** Street address * **City:** City name * **Country:** 2-letter country code (e.g., "US") * **Postal Code:** ZIP or postal code * **Tax ID:** VAT or tax identification number 3. Click **Save Changes** **Use Case:** * Required for invoicing * Needed for tax compliance * Displayed on receipts *** ### Roles and Permissions #### Default Roles **Organization Owner** * Full control over everything * Cannot be removed * Can transfer ownership * Only one per organization **Organization Admin** * Manage members and settings * Create and manage API keys * View billing information * Cannot transfer ownership **Member** * Basic access to organization resources * Can view usage statistics * Limited management capabilities #### Custom Roles ### Organizations can create custom roles with specific permissions. See [Roles & Permissions](/dashboard/interactive-blocks) for details. ### Best Practices #### Invitation Management * **Use work emails:** Ensure members use company email addresses * **Assign minimal roles:** Start with basic access, add more as needed * **Clean up pending invites:** Revoke old, unused invitations * **Document role assignments:** Keep track of who has what access #### Security * **Regular audits:** Review team members quarterly * **Remove immediately:** Deactivate access for departing employees * **Principle of least privilege:** Give only necessary permissions * **Monitor activity:** Check for unusual access patterns #### Organization * **Clear naming:** Use full names or clear identifiers * **Role documentation:** Document what each role should do * **Onboarding process:** Have a standard process for new members * **Offboarding checklist:** Ensure all access is removed when members leave *** ### Troubleshooting #### Invitation Not Received **Solutions:** 1. Check spam/junk folder 2. Verify email address is correct 3. Click **Resend** to send again 4. Contact support if issues persist #### Can't Assign Role **Possible causes:** * You don't have `roles.assign` permission * Target role doesn't exist * Member already has that role **Solutions:** * Ask an Owner or Admin to assign the role * Verify the role exists in Roles & Permissions * Check current roles in Manage Roles modal #### Can't Remove Member **Possible causes:** * Trying to remove yourself * Don't have `organization.remove` permission * Member is the organization owner **Solutions:** * Ask another Admin to remove you * Request permission from Owner * Transfer ownership first, then remove *** ### Permissions Required To manage team members, you need: * **Invite members:** `organization.invite` * **Remove members:** `organization.remove` * **Assign roles:** `roles.assign` * **Revoke roles:** `roles.revoke` * **Update organization:** `organization.update` *** ### Next Steps * Configure custom roles for granular access control * Set up API keys for team members * Review permissions to understand access levels * Monitor usage across your team # Roles & Permissions Control access to your organization with granular role-based permissions. Create custom roles tailored to your team's needs. ### Overview Roles define what actions users and API keys can perform. Each role contains a set of permissions that grant specific capabilities. **Key Concepts:** * **Roles:** Named collections of permissions (e.g., "Admin", "Read-only") * **Permissions:** Specific actions (e.g., `api.key.create`, `organization.invite`) * **Assignment:** Roles can be assigned to team members and API keys * **Inheritance:** Users can have multiple roles; permissions are combined *** ### System Roles Built-in roles cannot be edited or deleted. For example: #### Organization Owner * **Type:** Global (system-managed) * **Description:** Full control over the organization * **Permissions:** All permissions * **Assignment:** Automatically assigned to organization creator * **Limit:** One per organization * **Transfer:** Via ownership transfer feature #### Organization Admin * Manage organization settings * Invite and remove members * Create and manage API keys * View billing information * Cannot transfer ownership #### **Organization Member** * View organization resources * Use assigned API keys * View usage statistics * Limited management capabilities *** ### Custom Roles Create roles specific to your organization's needs. #### Creating a Role **Steps:** 1. **Open Creation Modal** * Navigate to the **Roles** tab * Click **+ Create Role** 2. **Enter Basic Information** * **Role Name:** Descriptive name (e.g., "Read-only Analyst") * **Description:** Optional explanation of the role's purpose 3. **Select Permissions** * Permissions are grouped by category * Check the boxes for permissions you want to include * See Permission Groups below for details 4. **Save Role** * Click **Create Role** * Role appears in the roles table * Can now be assigned to members and API keys #### Editing a Role Modify existing custom roles: **Steps:** 1. Find the role in the table 2. Click **Edit** 3. Update the name, description, or permissions 4. Click **Save Changes** **Effects:** * Changes apply immediately to all users/keys with this role * Users are not notified of permission changes * Consider communicating major changes to affected users > **Note:** You cannot edit system roles (they show a "View" button instead). #### Viewing a Role Inspect system roles or review custom roles: **Steps:** 1. Click **View** next to a system role (or **Edit** for custom roles) 2. See all assigned permissions 3. Permissions are grouped by category 4. Click **Close** when done #### Deleting a Role Remove custom roles that are no longer needed: **Steps:** 1. Click **Delete** next to the role 2. Confirm the action **Requirements:** * Role must not be assigned to any users or API keys * Cannot delete system roles **Effects:** * Role is permanently removed * Cannot be undone *** ### Permission Groups Permissions are organized into logical categories: #### Permissions * `permissions.view` - View system permissions #### Roles * `roles.create` - Create custom roles * `roles.view` - View roles and permissions * `roles.update` - Edit custom roles * `roles.delete` - Delete custom roles * `roles.assign` - Assign roles to members * `roles.revoke` - Remove roles from members #### Organization * `organization.view` - View organization details * `organization.update` - Edit organization information * `organization.invite` - Send invitations to new members * `organization.remove` - Remove members from organization * `organization.whitelist.view` - View whitelisted IPs * `organization.whitelist.manage` - Manage whitelisted IP labels #### API Keys * `api.key.create` - Create new API keys * `api.key.view` - View API key list and details * `api.key.update` - Edit API key names and roles * `api.key.revoke` - Revoke API keys #### Billing * `billing.checkout` - Create a checkout session * `billing.portal` - View subscription and payment information * `billing.update` - Change plans and payment methods * `billing.cancel` - Cancel subscriptions * `billing.resume` - Cancel subscriptions #### IP * `ip.query` - Query IP addresses *** ### Roles Table The roles table displays all available roles: | Column | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Role Name** | Display name of the role | | **Description** | Purpose and usage notes | | **Permissions** | Count of assigned permissions | | **Type** | Global (system) or Custom | | **Actions** | View, Edit, or Delete buttons | | **Type Badges:** | | *** ### Best Practices #### Role Design **Keep it simple:** * Create roles for common job functions * Avoid creating too many similar roles * Use clear, descriptive names **Principle of least privilege:** * Grant only necessary permissions * Start with minimal access * Add permissions as needed **Document roles:** * Use the description field * Maintain external documentation * Explain when to use each role #### Permission Management **Regular audits:** * Review roles quarterly * Remove unused roles * Verify permissions are still appropriate **Testing:** * Test new roles with a test account * Verify permissions work as expected * Check for unintended access **Communication:** * Inform users of role changes * Document permission requirements * Provide role assignment guidelines *** ### Assigning Roles #### To Team Members See Team Management for details on assigning roles to users. **Quick steps:** 1. Go to Team tab 2. Click **Manage Roles** next to a member 3. Select and assign roles #### To API Keys See API Keys for details on assigning roles to keys. **Quick steps:** 1. Go to API Keys tab 2. When creating or editing a key, select a role 3. Save the key *** ### Troubleshooting #### Can't Create Role **Possible causes:** * Don't have `roles.create` permission * Role name already exists * No permissions selected **Solutions:** * Ask an Owner or Admin for permission * Choose a unique role name * Select at least one permission #### Can't Delete Role **Possible causes:** * Role is assigned to users or API keys * Trying to delete a system role **Solutions:** * Remove role from all users and keys first * System roles cannot be deleted #### Permission Not Working **Check:** * User/key has the role assigned * Role includes the required permission * Permission is spelled correctly * Changes have been saved *** ### Permissions Required To manage roles, you need: * **Create roles:** `roles.create` * **Edit roles:** `roles.update` * **Delete roles:** `roles.delete` * **View roles:** `roles.view` * **Assign roles:** `roles.assign` * **Revoke roles:** `roles.revoke` *** ### Next Steps * Assign roles to team members * Create API keys with specific roles * Review organization permissions # Whitelist Control which IP addresses can access your API by maintaining a whitelist of approved IPs. This adds an extra layer of security to your organization. ### Overview The IP Whitelist feature allows you to: * Restrict API access to specific IP addresses * Label IPs for easy identification * Track when IPs were added * Manage your whitelist limit based on your plan **How it works:** * Only whitelisted IPs can make API requests * Requests from non-whitelisted IPs are rejected * Both IPv4 and IPv6 addresses are supported *** ### Adding IP Addresses **Steps:** 1. **Open Add Modal** * Navigate to the **Whitelist** tab * Click **+ Add IP Address** 2. **Enter IP Details** * **IP Address:** Enter the IP address * IPv4 format: `8.8.8.8` * IPv6 format: `2001:4860:4860::8888` * **Label (Optional):** Descriptive name (e.g., "Production Server", "Office Network") 3. **Save IP** * Click **Add IP** * IP appears in the whitelist table immediately * API access is granted instantly > **Tip:** Use labels to identify IPs easily. Include environment, location, or purpose. #### Checking Your Limit Before adding IPs, check your available slots: * View the **Whitelist Limit** card on the Overview tab * Shows "X / Y IPs used" (e.g., "3 / 50 IPs used") * Percentage indicator shows utilization **If you've reached your limit:** * Remove unused IPs * Upgrade your plan for more slots * A modal will prevent adding more IPs *** ### Managing Whitelisted IPs #### Whitelist Table The table displays all whitelisted IP addresses: | Column | Description | | -------------- | -------------------------------------- | | **IP Address** | The whitelisted IP (IPv4 or IPv6) | | **Label** | Your descriptive label (or "No Label") | | **Created** | Date the IP was added | | **Actions** | Edit and Remove buttons | #### Editing an IP Update the IP address or label: **Steps:** 1. Click **Edit** next to the IP 2. Modify the **IP Address** or **Label** 3. Click **Save Changes** **Use cases:** * Correct a typo in the IP * Update label for clarity * Change IP when server address changes #### Removing an IP Delete an IP from the whitelist: **Steps:** 1. Click **Remove** next to the IP 2. Confirm the action **Effects:** * IP is removed immediately * Requests from this IP will be rejected * Cannot be undone (must re-add if needed) > **Warning:** Ensure no active services are using this IP before removing it. *** ### Whitelist Limits by Plan Different subscription tiers have different IP limits: | Plan | IP Limit | | ---------------- | ---------------------- | | **Free Tier** | 1 IP address | | **Pro Monthly** | 2 IP addresses | | **Pro Yearly** | 5 IP addresses | | **Custom Plans** | Varies (contact sales) | #### Upgrading for More IPs If you need more IP addresses: 1. Go to the **Billing** tab 2. Select a higher-tier plan 3. Your IP limit increases immediately 4. Add additional IPs as needed #### Downgrading Impact > **Important:** When downgrading to a plan with fewer IP slots: > > * Oldest IPs exceeding the new limit are automatically deleted > * You'll see a warning before confirming the downgrade > * Review your whitelist before downgrading *** ### IP Address Formats #### IPv4 Addresses Standard format: `XXX.XXX.XXX.XXX` **Examples:** * `192.168.1.1` - Private network * `8.8.8.8` - Public DNS server * `10.0.0.5` - Private network * **Valid range:** `0.0.0.0` to `255.255.255.255` #### IPv6 Addresses Standard format: Eight groups of four hexadecimal digits **Examples:** * `2001:4860:4860::8888` - Google DNS * `2001:0db8:85a3:0000:0000:8a2e:0370:7334` - Full format * `::1` - Localhost (compressed) * **Compression:** Leading zeros and consecutive zero groups can be omitted *** ### Finding Your IP Address #### Current IP To find the IP address you're currently using, you can use our service: * Visit [ipaware.io](https://ipaware.io) #### Server IP To find your server's public IP: **Cloud Providers:** * AWS: Check EC2 instance details * Google Cloud: Check VM instance details * Azure: Check Virtual Machine overview **Command line (on the server):** ```bash curl ifconfig.me ``` *** ### Best Practices #### Security **Whitelist only necessary IPs:** * Don't add IPs "just in case" * Remove IPs when no longer needed * Regularly audit your whitelist **Use specific IPs:** * Avoid using dynamic IPs when possible * Use static IPs for production servers * Document IP ownership **Label everything:** * Always add descriptive labels * Include environment (prod, staging, dev) * Note the purpose or owner #### Organization **Naming conventions:** ``` [Environment] - [Purpose] - [Location] Examples: - "Production - API Server - AWS US-East" - "Staging - Test Server - Office" - "Dev - John's Laptop - Remote" ``` **Regular maintenance:** * Review whitelist monthly * Remove decommissioned servers * Update labels as infrastructure changes * Document IP changes in your change log #### Monitoring **Track usage:** * Note which IPs are actively making requests * Identify unused IPs * Monitor for unexpected access attempts **Plan ahead:** * Know your IP limit * Plan for growth * Upgrade before hitting limits *** ### Troubleshooting #### "IP Not Whitelisted" Error **Symptoms:** * API requests return 403 Forbidden * Error message mentions IP whitelist **Solutions:** 1. **Verify your IP:** ```bash curl ifconfig.me ``` 2. **Check whitelist:** * Ensure your IP is in the whitelist table * Verify the IP is exactly correct (no typos) 3. **Check for IP changes:** * Your IP may have changed (common with dynamic IPs) * Update the whitelist with your new IP 4. **IPv4 vs IPv6:** * Ensure you're using the correct IP version * Some networks use IPv6 by default #### Can't Add More IPs **Reason:** You've reached your plan's IP limit **Solutions:** 1. Remove unused IPs 2. Upgrade to a higher-tier plan 3. Consolidate services to use fewer IPs #### IP Keeps Changing **Problem:** Dynamic IP addresses change frequently **Solutions:** * **Contact ISP:** Request a static IP address * **Use VPN:** Route traffic through a static VPN IP * **Cloud proxy:** Use a cloud service with static IPs * **Upgrade plan:** Get more IP slots to accommodate changes #### Wrong IP Added **Fix:** 1. Click **Edit** next to the IP 2. Correct the IP address 3. Click **Save Changes** 4. Or remove and re-add with the correct IP. *** ### Advanced Use Cases #### Multiple Environments Organize IPs by environment: ``` Production: - 203.0.113.10 - "Prod - API Server 1" - 203.0.113.11 - "Prod - API Server 2" Staging: - 198.51.100.5 - "Staging - Test Server" Development: - 199.0.2.100 - "Dev - Office Network" ``` #### Load Balancers When using load balancers: * Whitelist the load balancer's IP, not individual servers * Label clearly: "Prod - Load Balancer - AWS ELB" * Update if load balancer IP changes #### CI/CD Pipelines For automated testing: * Whitelist your CI/CD runner IPs * Label: "CI/CD - GitHub Actions" * Use static IPs or IP ranges if supported *** ### Permissions Required To manage the whitelist, you need: * **Add IPs:** `organization.whitelist.manage` * **Edit IPs:** `organization.whitelist.manage` * **Remove IPs:** `organization.whitelist.manage` * **View whitelist:** `organization.whitelist.view` *** ### Next Steps * Create API keys to use with whitelisted IPs * Monitor usage from whitelisted IPs * Upgrade plan for more IP slots * Configure roles to control whitelist access # Settings Manage your account security, authentication methods, and active sessions from the Settings tab. ### Overview The Settings tab provides access to: * Email and password management * Two-factor authentication (2FA) * Passkey registration * Active session management * Account deletion *** ### Account Security #### Changing Your Email Update your account email address: **Steps:** 1. Click **Change Email** 2. Enter your **current password** for verification 3. Enter your **new email address** 4. Click **Update** **What happens:** * Verification email sent to new address * Notification sent to old address * You're signed out automatically * Click link in verification email to confirm * Sign in with new email address > **Security:** You can revert the change using the link in the notification email sent to your old address. #### Changing Your Password Update your account password: **Steps:** 1. Click **Change Password** 2. Enter your **current password** 3. Enter your **new password** (minimum 8 characters) 4. Click **Update** **Password** **Requirements:** * At least 8 characters * Recommended: Mix of uppercase, lowercase, numbers, and symbols * Don't reuse passwords from other services > **Tip:** Use a password manager to generate and store strong passwords. *** ### Two-Factor Authentication (2FA) Add an extra layer of security with time-based one-time passwords (TOTP). #### Enabling 2FA **Requirements:** * Authenticator app (Google Authenticator, Authy, 1Password, etc.) **Steps:** 1. **Start Setup** * Click **Enable 2FA** * A QR code appears 2. **Scan QR Code** * Open your authenticator app * Scan the QR code with your phone * Alternatively, manually enter the secret key shown 3. **Verify Setup** * Enter the 6-digit code from your authenticator app * Click **Verify & Enable** 4. **Save Recovery Codes** * **CRITICAL:** Copy and store your recovery codes securely * Each code can only be used once * You'll need these if you lose access to your authenticator * Click **Done** when saved **Status:** * Badge changes to "ENABLED" (green) * 2FA required for all future logins * Recovery codes stored securely > **Important:** Store recovery codes in a safe place (password manager, secure note). You cannot view them again! #### Using 2FA After enabling, you'll need to provide a code when signing in: 1. Enter email and password 2. Enter 6-digit code from authenticator app 3. Or click **Verify** **Using Recovery Code:** * If you don't have your authenticator, click "Use Recovery Code" * Enter one of your saved recovery codes * Each code works only once #### Disabling 2FA Remove 2FA from your account: **Steps:** 1. Click **Disable** 2. Verify with either: * **TOTP Code:** From your authenticator app * **Recovery Code:** One of your saved codes 3. Click **Disable** **Effects:** * 2FA is removed immediately * Badge changes to "DISABLED" * Only password required for login *** ### Passkeys Use biometric authentication or hardware security keys for passwordless login. #### What are Passkeys? Passkeys use WebAuthn technology to provide: * **Passwordless login:** No password needed * **Phishing-resistant:** Cannot be stolen or phished * **Convenient:** Use fingerprint, Face ID, or security key * **Secure:** Cryptographic keys stored on your device #### Adding a Passkey **Requirements:** * Compatible device (modern phone, laptop, or security key) * Browser with WebAuthn support (Chrome, Safari, Firefox, Edge) **Steps:** 1. **Start Registration** * Click **Add Passkey** * Browser prompts you to create a passkey 2. **Authenticate** * Choose authentication method: * Fingerprint scanner * Face ID * Security key (YubiKey, etc.) * Device PIN * Follow browser prompts 3. **Name Your Passkey** * Enter a friendly name (e.g., "iCloud Keychain", "YubiKey") * Click **Save** 4. **Confirmation** * Passkey appears in the table * Can now be used for login #### Managing Passkeys The passkeys table shows: | Column | Description | | ------------- | ---------------------------- | | **Name** | Your friendly label | | **Created** | Date registered | | **Last Used** | Last login with this passkey | | **Device** | Device type and browser | | **Actions** | Rename and Remove buttons | #### **Renaming a Passkey:** 1. Click **Rename** 2. Enter new name 3. Click **Save** #### **Removing a Passkey:** 1. Click **Remove** 2. Confirm the action 3. Passkey is deleted immediately > **Note:** You can have multiple passkeys for different devices. #### Using Passkeys to Sign In 1. On login page, click **Sign in with a Passkey** 2. Browser prompts you to select a passkey 3. Authenticate (fingerprint, Face ID, etc.) 4. Signed in automatically *** ### Session Management Monitor and control devices logged into your account. #### Active Sessions Table View all active sessions: | Column | Description | | -------------------- | ------------------------------------------------- | | **Device / Browser** | Device type and browser (e.g., "Chrome on macOS") | | **Location** | City and country based on IP | | **Last Active** | Last activity timestamp | | **Status** | Active (green badge) | | **Actions** | Log Out button (or "Current" for your session) | #### Refreshing Sessions Update the session list: * Click **Refresh** button * Table updates with latest activity #### Logging Out a Session Remove access from a specific device: **Steps:** 1. Find the session in the table 2. Click **Log Out** 3. Confirm the action **Effects:** * Device is signed out immediately * Session removed from table * User must sign in again on that device > **Use case:** Log out forgotten sessions, remove access from lost devices, or sign out shared computers. #### Logging Out All Other Sessions Sign out all devices except your current one: **Steps:** 1. Click **Log Out All Other Sessions** 2. Confirm the action **Effects:** * All other devices are signed out * Only your current session remains * Useful after password change or security concern *** ### Account Deletion #### Danger Zone Permanently delete your account and all associated data. **Steps:** 1. Click **Delete Account** 2. Read the warning carefully 3. Enter your **password** to confirm 4. Click **Delete Account** **What gets deleted:** * Your user account * All API keys (deactivated immediately) * Personal settings and preferences * Active sessions **What happens to organization:** * If you're the owner: Must transfer ownership first * If you're a member: Removed from organization * Organization data remains intact > **Warning:** This action is permanent and cannot be undone! **Before deleting:** * Export any data you need * Transfer ownership if you're the owner * Revoke API keys manually if needed * Inform your team *** ### Security Best Practices #### Account Protection **Enable multiple authentication methods:** * Set a strong password * Enable 2FA * Register at least one passkey * Keep recovery codes safe **Regular maintenance:** * Review active sessions weekly * Remove old passkeys from unused devices * Update password every 90 days * Check for suspicious activity #### Session Security **Best practices:** * Always sign out on shared computers * Don't save passwords in public browsers * Use private/incognito mode on untrusted devices * Review session locations for anomalies **Red flags:** * Sessions from unknown locations * Devices you don't recognize * Unusual activity times * Multiple concurrent sessions **If compromised:** 1. Change password immediately 2. Log out all other sessions 3. Enable 2FA if not already enabled 4. Review API keys and revoke suspicious ones 5. Contact support *** ### Troubleshooting #### Can't Change Email **Solutions:** * Verify current password is correct * Ensure new email isn't already in use * Check spam folder for verification email * Wait a few minutes and try again #### 2FA Code Not Working **Common issues:** * **Time sync:** Ensure device time is accurate * **Wrong code:** Code changes every 30 seconds * **Old code:** Generate a new code * **Wrong account:** Verify you're using correct authenticator entry **Solutions:** * Sync your device time * Use a recovery code instead * Contact support if locked out #### Passkey Registration Failed **Possible causes:** * Browser doesn't support WebAuthn * Device doesn't have biometric capability * Security key not connected properly **Solutions:** * Update your browser * Try a different device * Use a hardware security key * Check browser compatibility #### Unknown Session Appears **Immediate actions:** 1. Log out that session 2. Change your password 3. Enable 2FA 4. Review API keys 5. Contact support *** ### Permissions Required Most settings are self-service and don't require special permissions. However: * **View settings:** All users * **Modify own settings:** All users * **Delete account:** Account owner only *** ### Next Steps * Enable 2FA for better security * Add a passkey for convenient login * Review active sessions regularly * Manage API keys for application access # Billing Manage your IPAware subscription, view pricing plans, and handle payment information. ### Overview The Billing tab allows you to: * View your current subscription * Compare available plans * Upgrade or downgrade your plan * Manage payment methods * View invoices and billing history * Cancel or resume subscriptions *** ### Subscription Plans #### Free Tier **Perfect for:** Testing and small projects **Features:** * 5,000 requests / month * Basic geolocation data * 1 whitelisted IP address * Basic support * **Price:** $0 / month #### Pro Monthly **Perfect for:** Growing businesses **Features:** * **UNLIMITED requests** * Full API access * 2 whitelisted IP addresses * Advanced threat detection * 24/7 priority email support * Commercial usage * **Price:** $9.99 / month #### Pro Yearly **Perfect for:** Established businesses **Features:** * **UNLIMITED requests** * Full API access * 5 whitelisted IP addresses * Advanced threat detection * 24/7 priority email support * Commercial usage * **Annual billing discount** * Cost savings vs monthly * **Price:** $99.99 / month #### Custom Plans **Perfect for:** Enterprise needs **Features:** * Unlimited requests * Custom solutions * Custom whitelisted IP limits * Dedicated support manager * Custom contracts & SLA * Volume discounts * **Price:** Contact sales *** ### Current Subscription Your current plan is displayed at the top of the Billing tab. **Information shown:** * Plan name * Subscription status (Active, Canceled, etc.) * Current billing period dates * Renewal date * Special status badges (if applicable) **Status Badges:** * **Active** (Green) - Subscription is current * **Will Not Renew** (Red) - Canceled, expires at period end * **Scheduled Change** (Yellow) - Plan change pending *** ### Upgrading Your Plan #### From Free to Paid **Steps:** 1. **Select Plan** * Browse available plans * Click **Upgrade** on your chosen plan 2. **Stripe Checkout** * Redirected to secure Stripe checkout * Enter payment information * Review and confirm 3. **Activation** * Redirected back to console * Plan activates immediately * Success message displayed **What changes:** * Request quota increases * IP whitelist limit increases * Access to advanced features * Priority support enabled #### Switching Between Paid Plans Change from one paid plan to another: **Steps:** 1. Click **Switch Plan** on the desired plan 2. Review the change details 3. Confirm the switch **Important:** * Change takes effect at end of current billing period * You keep current plan benefits until then * "Scheduled Change" badge appears * No immediate charge **Downgrade warning:** * If new plan has fewer IP slots, oldest IPs are automatically removed * Review your whitelist before confirming *** ### Managing Your Subscription #### Viewing Billing Portal Access Stripe's customer portal for full billing management: **Steps:** 1. Click **Manage Billing & Invoices** 2. Redirected to Stripe portal **In the portal you can:** * Update payment methods * View invoice history * Download receipts * Update billing information * View upcoming invoices #### Canceling Subscription Stop your subscription from renewing: **Steps:** 1. Click **Cancel Subscription** 2. Read the warning about downgrade impacts 3. Click **Confirm Cancellation** **What happens:** * Subscription remains active until period end * "Will Not Renew" badge appears * Access continues until expiration * Automatically downgrades to Free Tier * IP whitelist reduced to 1 (oldest IPs removed) #### Resuming Subscription Reactivate a canceled subscription: **Steps:** 1. Click **Resume Subscription** (appears if canceled) 2. Confirm the action **Effects:** * Subscription will renew at period end * "Will Not Renew" badge removed * No immediate charge * Benefits continue uninterrupted *** ### Payment Methods #### Adding a Payment Method Done during initial upgrade through Stripe Checkout. #### Updating Payment Method **Steps:** 1. Click **Manage Billing & Invoices** 2. In Stripe portal, click **Payment methods** 3. Add new card or update existing 4. Set as default if desired **Supported methods:** * Credit cards (Visa, Mastercard, Amex) * Debit cards * Other methods supported by Stripe #### Failed Payments If a payment fails: 1. **Email notification** sent immediately 2. **Retry attempts** made automatically 3. **Downgrade** to Free Tier if unresolved **To resolve:** * Update payment method in Stripe portal * Ensure sufficient funds * Contact support if issues persist *** ### Invoices #### Viewing Invoices **Steps:** 1. Click **Manage Billing & Invoices** 2. View invoice list in Stripe portal 3. Click any invoice to view details **Invoice includes:** * Invoice number * Billing period * Amount charged * Payment method * Organization details * Tax information (if applicable) #### Downloading Invoices From Stripe portal: 1. Open the invoice 2. Click **Download PDF** 3. Save for your records **Use cases:** * Expense reports * Tax filing * Accounting records * Reimbursement requests *** ### Billing Information #### Organization Details Update billing information for invoices: **Steps:** 1. Go to **Team** tab 2. Click **Edit Details** 3. Update organization information: * Name * Address * City, Country, Postal Code * Tax ID (for VAT) 4. Click **Save Changes** **Appears on:** * All future invoices * Receipts * Tax documents *** ### Understanding Billing Cycles #### Billing Period **Monthly plans:** * Billed on the same day each month * Example: Subscribed on Jan 15 β†’ billed on 15th of each month **Yearly plans:** * Billed once per year * Typically 2 months free compared to monthly #### Proration **When upgrading mid-cycle:** * Charged prorated amount for remainder of period * Full new rate applies next billing cycle **When downgrading:** * Change takes effect at end of current period * No refund for current period * New rate applies next billing cycle #### Trial Periods Free Tier serves as the trial: * No credit card required * 5,000 requests to test the API * Upgrade anytime *** ### Plan Comparison | Feature | Free | Pro Monthly | Pro Yearly | Custom | | -------------------- | ----- | -------------- | -------------- | ----------------- | | **Requests/month** | 5,000 | Unlimited | Unlimited | Unlimited | | **IP Whitelist** | 1 | 2 | 5 | Custom | | **Threat Detection** | ❌ | βœ… | βœ… | βœ… | | **Support** | Basic | Priority Email | Priority Email | Dedicated Manager | | **Commercial Use** | ❌ | βœ… | βœ… | βœ… | | **SLA** | ❌ | ❌ | ❌ | βœ… | | **Custom Contract** | ❌ | ❌ | ❌ | βœ… | *** ### Troubleshooting #### Payment Declined **Common reasons:** * Insufficient funds * Card expired * Incorrect billing address * Bank security hold **Solutions:** 1. Verify card details 2. Contact your bank 3. Try a different payment method 4. Update billing address #### Can't Upgrade **Possible issues:** * Browser blocking Stripe redirect * Ad blocker interfering * Network connectivity **Solutions:** * Disable ad blockers * Try different browser * Check internet connection * Contact support #### Unexpected Charge **Check:** * Billing period (monthly vs yearly) * Plan changes * Proration for mid-cycle upgrade * Invoice in Stripe portal **If still unclear:** * Review invoice details * Contact support with invoice number *** ### Best Practices #### Cost Management **Monitor usage:** * Check request counts regularly * Plan upgrades before hitting limits * Use Free Tier for development **Optimize costs:** * Choose yearly billing for savings * Remove unused IP whitelist entries * Consolidate API keys **Budget planning:** * Set reminders for renewal dates * Review invoices monthly * Track usage trends *** ### Getting Help #### Sales Questions For custom plans or enterprise needs: * Email: * Include your requirements * Mention expected usage volume #### Billing Support For payment or invoice issues: * Email: * Include invoice number * Describe the issue clearly #### Technical Support For API or technical questions: * Email: * Priority support for paid plans *** ### Next Steps * Monitor usage to choose the right plan * Manage IP whitelist to maximize your limit * Create API keys to start using the API * Invite team members to collaborate # WHOIS Lookup Analyze any IP address for threat signals, geolocation data, and network information using the built-in WHOIS lookup tool. ### Overview The WHOIS Lookup tool provides comprehensive IP intelligence including: * **Geolocation:** Country, region, city, timezone * **Network Information:** ASN, organization, CIDR * **Security Intelligence:** Threat detection, risk scoring, recommendations * **Infrastructure Analysis:** Datacenter detection, anycast identification *** ### Performing a Lookup **Steps:** 1. **Navigate to Tool** * Click **Whois Lookup** in the sidebar 2. **Enter IP Address** * Type the IP address in the search field * Supports both IPv4 and IPv6 * Examples: * IPv4: `8.8.8.8` * IPv6: `2001:4860:4860::8888` 3. **Search** * Click **Lookup** * Results appear within seconds 4. **Review Results** * Data organized into clear sections * JSON view available for raw data *** ### Understanding Results #### Location Information **Data provided:** * **Country:** Full name and 2-letter code * **Region:** State or province * **City:** City name * **Timezone:** IANA timezone identifier * **Coordinates:** Latitude and longitude (in JSON) * **Postal Code:** ZIP or postal code (in JSON) * **Continent:** Continent name and code (in JSON) **Example:** ``` Country: United States (US) Region: California City: Mountain View Timezone: America/Los_Angeles ``` **Use cases:** * Verify user location * Detect VPN/proxy usage * Geofencing and compliance * Localized content delivery #### Network Information **Data provided:** * **ASN:** Autonomous System Number * **Organization:** ISP or hosting provider * **CIDR:** Network range * **Anycast:** Whether IP uses anycast routing **Example:** ``` ASN: 15169 Organization: Google LLC CIDR: 8.8.8.0/24 Anycast: Yes ``` **Use cases:** * Identify hosting providers * Detect cloud services * Network troubleshooting * Infrastructure analysis #### Security Intelligence The most powerful feature - comprehensive threat analysis. **Risk Assessment:** * **Trust Score:** 0-100 (higher is better) * **Risk Score:** 0-100 (lower is better) * **Threat Level:** Low, Medium, High, Critical * **Recommendation:** Allow, Flag, or Block **Security Indicators:** * **Is Proxy:** Anonymous proxy detection * **Is Datacenter:** Hosting/datacenter IP * **Is Threat:** Known malicious activity * **Is Satellite:** Satellite provider * **Threat Types:** Specific threat categories (in JSON) **Example - Safe IP:** ``` Trust Score: 95 Risk Score: 5 Threat Level: LOW RISK Recommendation: ALLOW Infrastructure: Residential/Consumer ``` **Example - Risky IP:** ``` Trust Score: 20 Risk Score: 85 Threat Level: HIGH RISK Recommendation: BLOCK Infrastructure: Datacenter ``` **Color coding:** * 🟒 **Green (Allow):** Safe to allow * 🟑 **Yellow (Flag):** Monitor or challenge * πŸ”΄ **Red (Block):** High risk, consider blocking *** ### Use Cases #### Fraud Prevention **Scenario:** E-commerce checkout **Check for:** * Datacenter IPs (potential fraud) * High risk scores * Mismatched geolocation * Known threat IPs **Action:** * Trust Score < 50: Require additional verification * Recommendation = Block: Reject transaction * Datacenter IP: Flag for manual review #### Account Security **Scenario:** Login attempt from new location **Check for:** * Unusual location vs user's history * Proxy/VPN usage * Threat indicators **Action:** * Different country: Trigger 2FA * Proxy detected: Send verification email * High risk: Block and notify user #### API Access Control **Scenario:** Rate limiting and access decisions **Check for:** * Datacenter vs residential * Known malicious IPs * Geographic restrictions **Action:** * Datacenter: Apply stricter rate limits * Threat detected: Block API access * Restricted country: Deny access #### Content Delivery **Scenario:** Serving localized content **Use:** * Country and region data * Timezone information * Language preferences **Action:** * Redirect to regional site * Display localized content * Set appropriate timezone *** ### JSON Response Click to view the raw JSON response for programmatic use. **Structure:** ```json { "ip": { "address": "8.8.8.8", "version": "IPv4", "network_start": "8.8.8.0", "network_end": "8.8.8.255" }, "location": { "country": "United States", "country_code": "US", "region": "California", "city": "Mountain View", "time_zone": "America/Los_Angeles", "latitude": 37.386, "longitude": -122.0838 }, "security": { "is_proxy": false, "is_datacenter": true, "is_threat": false, "threat_level": "low", "risk_score": 15, "trust_score": 85, "recommendation": "allow" }, "connection": { "asn": 15169, "org": "Google LLC", "asn_cidr": "8.8.8.0/24" } } ``` **Use cases:** * Copy for API integration testing * Save for documentation * Analyze patterns * Debugging *** ### Best Practices #### Interpreting Results **Trust Score guidelines:** * **90-100:** Highly trustworthy * **70-89:** Generally safe * **50-69:** Moderate caution * **Below 50:** High caution **Risk Score guidelines:** * **0-25:** Low risk * **26-50:** Moderate risk * **51-75:** High risk * **76-100:** Critical risk **Recommendations:** * **Allow:** Safe to proceed * **Flag:** Add extra verification * **Block:** High risk, consider denying #### Decision Making **Don't rely solely on one indicator:** * Combine multiple signals * Consider context (user behavior, history) * Use risk scores as guidance, not absolute rules * Implement tiered responses **Example decision tree:** ``` If risk_score > 75: β†’ Block Else if risk_score > 40: β†’ Require 2FA Else if is_datacenter: β†’ Flag for review Else: β†’ Allow ``` *** ### Limitations **Data accuracy:** * Geolocation is approximate (city-level) * IP ownership can change * VPNs may mask true location * Mobile IPs may show carrier location **Not a replacement for:** * Comprehensive fraud detection * Full security audits * Legal compliance verification * Identity verification **Use as part of:** * Multi-factor authentication * Layered security approach * Risk-based decision making * User behavior analysis *** ### Troubleshooting #### "Invalid IP address format" **Cause:** IP address is malformed **Solutions:** * Verify IPv4 format: `XXX.XXX.XXX.XXX` * Verify IPv6 format: Valid hex groups * Remove extra spaces * Don't include port numbers #### Incomplete Data **Possible reasons:** * IP is newly allocated * Private/internal IP address * Limited database coverage * IP is reserved/special use **What to do:** * Verify IP is public * Try again later * Check if IP is in private range * Reach out to and submit a correction *** ### Privacy Considerations **What's logged:** * IP addresses you look up * Timestamp of lookup * Your user ID **What's NOT logged:** * Why you're looking up the IP * What you do with the results * Associated user data **Data retention:** * Lookup history: 90 days * Rate limit counters: 60 seconds *** ### API Integration For programmatic access to IP intelligence: **Use the API endpoint.** **Benefits:** * Batch lookups * Automated integration * Real-time threat detection See [API Documentation](https://api-docs.ipaware.io/) for details. *** ### Next Steps * Create API keys for programmatic access * Set up whitelist based on lookup results * Monitor usage to track API consumption * Review security settings for your account # Help Center

What can we help you find?

Browse the topics below or use the AI assistant to ask anything you need help with.

Ask AI Website