Authentication across our APIs is done via secure API keys. These keys are assigned to specific users on your account and inherit permissions from those users, ensuring proper access control and security.

Public Keys: Used for client-side operations and non-sensitive transactions
Private Keys: Used for server-side operations requiring full access and sensitive data handling

Security Note: Always select the key type that aligns with your specific use case. Using the wrong key type can create security vulnerabilities or limit functionality.

Getting Your API Keys

For Merchants

To generate API keys as a merchant:

Log into your Merchant Portal
Navigate to Settings > Security Keys
Click Add a New Key
Add a descriptive Key Name for easy identification
Select the username you want to associate with this key.
Select the Key Permission type and select Create.

For Partners

To create API keys as a partner:

Log into your Partner Portal
Go to Settings > Security Keys
Click Add a New Key
Add a descriptive Key Name for easy identification
Select the username you want to associate with this key.
Select the Key Permission type and select Create.

Authentication Methods

Include your API key in the request header:

curl -X GET "https://sandbox.nmi.com/api/v5/endpoint" \
  -H "Authorization: YOUR_API_KEY"

For Classic APIs, include your API key in the Request Body:

{
  "api_key": "YOUR_API_KEY",
  "other_data": "value"
}

Key Management

Creating Multiple Keys

We recommend generating different API keys for different purposes:

Development: For testing and development environments
Production: For live production systems
Team Members: Individual keys for different developers
Applications: Separate keys for different applications or services

Rotating API Keys

If a key is compromised or for regular security maintenance:

Generate New Key: Create a replacement key with the same permissions
Update Applications: Replace the old key in all applications
Test Functionality: Verify all systems work with the new key
Revoke Old Key: Delete the compromised key from your account
Document Change: Update your security documentation

Key Permissions

API keys inherit permissions from the user account they're associated with. Ensure:

Users have appropriate role-based access controls
Keys are assigned to accounts with minimal required permissions
Permissions are reviewed and updated regularly
Unused or excessive permissions are removed

Integration Examples

Basic Authentication Request

// Node.js example
const axios = require('axios');
const response = await axios.get('https://sandbox.nmi.com/api/v5/endpoint', {
  headers: {
    'Authorization': `${process.env.API_KEY}`,
    'Content-Type': 'application/json'
  }
});

Error Handling

Always implement proper error handling for authentication:

try {
  const response = await makeAPIRequest();
  return response.data;
} catch (error) {
  if (error.response?.status === 401) {
    throw new Error('Authentication failed. Check your API key.');
  } else if (error.response?.status === 403) {
    throw new Error('Access forbidden. Insufficient permissions.');
  }
  throw error;
}

Common Issues & Troubleshooting

exclamation-triangle

401 Unauthorized

Causes:

Invalid or expired API key
Missing Authorization header
Incorrect key format

Solutions:

Verify key is correct and active
Check header formatting
Regenerate key if necessary

ban

403 Forbidden

Causes:

Insufficient permissions
Account restrictions
Rate limit exceeded

Solutions:

Review key permissions
Contact support for account issues
Implement rate limiting

question-circle

Key Not Working

Causes:

Wrong environment (test vs. live)
Key type mismatch
Account configuration issues

Solutions:

Verify environment settings
Check public vs. private key usage
Review account configuration

shield-alt

Security Concerns

Actions:

Immediately rotate compromised keys
Review access logs
Update security practices
Contact support if needed

Prevention:

Regular security audits
Secure key storage
Access monitoring