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 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