Service Keys

Service keys provide permanent authentication for programmatic access to the Nexla platform. These keys are designed for server-to-server communication, automated workflows, and integration scenarios where interactive authentication is not feasible.

About Service Keys

Service keys provide permanent, secure authentication credentials designed specifically for automated systems and production environments. Unlike session tokens that expire and require user interaction, service keys offer continuous authentication capabilities that are essential for server-to-server communication, automated workflows, and integration scenarios.

Key advantages of service keys:

• Permanent authentication: No expiration means no interruption to automated processes
• Server-to-server communication: Designed for machine-to-machine authentication
• Scalable integration: Support high-volume API interactions without user intervention
• Enterprise security: Built-in security features including encryption, audit logging, and access controls
• Operational efficiency: Eliminate the need for manual authentication in automated systems

Service keys are ideal for:

• Production Systems: Long-running applications and services
• Automated Workflows: CI/CD pipelines and scheduled jobs
• Server Applications: Backend services and microservices
• Integration Scenarios: Third-party system connections
• Monitoring Tools: Automated monitoring and alerting systems

Service Key Characteristics

Service keys are designed with enterprise-grade security and operational flexibility in mind. Understanding these characteristics helps you implement service keys effectively and securely in your applications.

Key Features

Service keys provide several fundamental features that make them ideal for production environments and automated systems. These features ensure reliability, security, and operational efficiency.

• Permanent: Service keys do not expire unless manually rotated or deactivated
• Secure: Keys are encrypted and stored using enterprise-grade security measures
• Auditable: All service key usage is logged for security monitoring and compliance
• Rotatable: Keys can be rotated without disrupting ongoing operations
• Scoped: Keys can be limited to specific organizations and permissions

Security Benefits

The security architecture of service keys provides multiple layers of protection while maintaining operational efficiency. These benefits make service keys the preferred choice for production authentication.

• No Expiration: Eliminates the need for frequent re-authentication
• Encrypted Storage: Keys are never stored in plain text
• Usage Monitoring: Track all API calls made with each service key
• Access Control: Limit keys to specific resources and operations

Creating Service Keys

Service keys can be created through two different methods depending on your needs and workflow preferences. Each method offers distinct advantages for different use cases and security requirements. Understanding when to use each approach helps ensure optimal security and operational efficiency.

Creation method considerations:

• UI Creation: Best for one-time setup and manual key management
• API Creation: Ideal for automated provisioning and infrastructure as code
• Security Context: Both methods require appropriate authentication and permissions
• Key Management: Consider how keys will be stored and managed after creation

Via the Nexla UI

The easiest way to create a service key is through the Nexla web interface. This method is ideal for initial setup, one-time key creation, and scenarios where you need immediate visual feedback and confirmation. The UI provides a user-friendly interface that guides you through the creation process with built-in validation and security checks.

UI creation benefits:

• Immediate feedback: See the key immediately after creation
• Visual confirmation: Clear indication of successful key generation
• Built-in validation: Automatic checks for proper key configuration
• User-friendly: No programming knowledge required
• Secure display: One-time display with copy-to-clipboard functionality

Step-by-step process:

Follow these steps to create a service key through the Nexla UI. The process is straightforward and takes only a few minutes to complete:

1. Navigate to Settings: Go to your Nexla UI instance
2. Access Authentication: Navigate to Settings → Authentication
3. Create Service Key: Click the Create Service Key button
4. Configure Key: Provide a name and description for the key
5. Copy Key: Copy the generated service key immediately (it won't be shown again)

Via the Nexla API

You can also create service keys programmatically using the Nexla API. This method is essential for automated provisioning, infrastructure as code implementations, and scenarios where you need to create multiple keys or integrate key creation into your deployment pipelines. API-based creation enables full automation and integration with your existing tools and workflows.

API creation benefits:

• Automated provisioning: Integrate key creation into deployment pipelines
• Infrastructure as code: Version control your key creation processes
• Bulk operations: Create multiple keys efficiently
• Integration: Work with existing automation tools and scripts
• Consistency: Ensure uniform key naming and configuration across environments

API request example:

The following example demonstrates how to create a service key using the Nexla API. This POST request creates a new service key with the specified name and description. You'll need a valid access token with appropriate permissions to create service keys.

Create Service Key via API

curl -X POST <nexla-api-endpoint>/service_keys \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Integration Key",
    "description": "Service key for production system integration"
  }'

Using Service Keys for Authentication

Service keys use a two-step authentication process: first, you exchange your service key for a session token, then use that token for API calls. This approach provides enhanced security while maintaining the convenience of permanent credentials. The two-step process ensures that service keys are never transmitted directly with API requests, reducing the risk of key exposure and enabling better security monitoring and control.

Authentication flow benefits:

• Enhanced security: Service keys are never sent directly with API requests
• Session management: Leverage existing session token infrastructure
• Audit capability: Track both key usage and session activity separately
• Flexible expiration: Session tokens can expire while service keys remain valid
• Revocation control: Revoke sessions without affecting the underlying service key

Basic Authentication

To authenticate using a service key, make a POST request to the /token endpoint with the service key in the Authorization header. This step converts your permanent service key into a temporary session token that can be used for API operations. The service key must be Base64-encoded and sent using Basic authentication format, following standard HTTP authentication protocols.

Authentication requirements:

• Base64 encoding: Service key must be properly encoded for Basic auth
• HTTPS required: All authentication requests must use secure connections
• Proper headers: Include appropriate Accept and Content-Type headers
• Empty body: The request body should be empty for token exchange
• Error handling: Implement proper error handling for authentication failures

Service Key Authentication Request

curl -X POST <nexla-api-endpoint>/token              \
  -H "Authorization: Basic <service-key>"            \
  -H "Accept: application/vnd.nexla.api.v1+json"     \
  -H "Content-Length: 0"

Authentication Response

The response will include a session access token that can be used for subsequent API calls. The response provides comprehensive information about the authenticated session, including user details, organization context, and token metadata. This information is essential for understanding the scope and permissions of your authenticated session.

Response components:

• Access token: The session token for API authentication
• Token metadata: Expiration time and token type information
• User context: Service account details and permissions
• Organization context: Organization ID and details for multi-tenant scenarios
• Security flags: Indicators for super user status and impersonation

Service Key Authentication Response

{
  "access_token": "<session-access-token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": 12345,
    "email": "service@example.com",
    "full_name": "Service Account",
    "api_key": "<service-key>",
    "super_user": false,
    "impersonated": false
  },
  "org": {
    "id": 9876,
    "name": "Example Organization",
    "description": "Organization Description"
  }
}

Code Examples

The following code examples demonstrate how to implement service key authentication in different programming languages. These examples show the complete authentication flow from service key to session token, followed by API usage. Each example includes proper error handling and follows security best practices.

Implementation considerations:

• Secure storage: Store service keys securely using environment variables or credential managers
• Error handling: Implement comprehensive error handling for authentication failures
• Token management: Handle token expiration and refresh scenarios
• Security headers: Use appropriate headers for all API requests
• Connection security: Ensure all requests use HTTPS

Python implementation:

The following Python example demonstrates complete service key authentication using the requests library. This example shows how to encode the service key for Basic authentication, exchange it for a session token, and then use that token for API calls.

Python Service Key Authentication

import requests
import base64

# Encode service key for Basic auth
service_key = "your-service-key-here"
encoded_key = base64.b64encode(service_key.encode()).decode()

headers = {
    'Authorization': f'Basic {encoded_key}',
    'Accept': 'application/vnd.nexla.api.v1+json'
}

# Get session token
response = requests.post('https://api.nexla.io/token', headers=headers)
token_data = response.json()
session_token = token_data['access_token']

# Use session token for API calls
api_headers = {
    'Authorization': f'Bearer {session_token}',
    'Accept': 'application/vnd.nexla.api.v1+json'
}

teams_response = requests.get('https://api.nexla.io/teams', headers=api_headers)

JavaScript implementation:

The following JavaScript example demonstrates service key authentication using the Fetch API. This example shows how to encode the service key using btoa(), handle the authentication flow with promises, and make subsequent API calls with the session token.

JavaScript Service Key Authentication

const serviceKey = 'your-service-key-here';
const encodedKey = btoa(serviceKey);

// Get session token
fetch('https://api.nexla.io/token', {
    method: 'POST',
    headers: {
        'Authorization': `Basic ${encodedKey}`,
        'Accept': 'application/vnd.nexla.api.v1+json'
    }
})
.then(response => response.json())
.then(tokenData => {
    const sessionToken = tokenData.access_token;
    
    // Use session token for API calls
    return fetch('https://api.nexla.io/teams', {
        headers: {
            'Authorization': `Bearer ${sessionToken}`,
            'Accept': 'application/vnd.nexla.api.v1+json'
        }
    });
})
.then(response => response.json())
.then(teams => console.log(teams));

Service Key Management

The Nexla API provides comprehensive endpoints for managing service keys throughout their lifecycle. These management capabilities enable you to maintain security, track usage, and ensure operational efficiency across your service key infrastructure. Proper service key management is essential for maintaining security posture and ensuring that your integrations remain functional and secure.

Management capabilities:

• Lifecycle control: Create, update, rotate, pause, and delete service keys
• Security monitoring: Track key usage and identify potential security issues
• Operational flexibility: Pause keys temporarily without permanent deletion
• Audit compliance: Maintain comprehensive audit trails of key management activities
• Integration continuity: Rotate keys without disrupting existing integrations

List Service Keys

Retrieve all service keys in your account to get a comprehensive view of your service key inventory. This endpoint provides detailed information about each service key, including creation dates, last usage, and current status. Regular listing of service keys helps maintain security awareness and ensures proper key management practices.

Listing benefits:

• Inventory management: Maintain awareness of all active service keys
• Security auditing: Identify unused or potentially compromised keys
• Usage tracking: Monitor key activity and usage patterns
• Compliance reporting: Generate reports for security audits
• Operational planning: Plan key rotation and maintenance schedules

API request example:

The following example demonstrates how to retrieve all service keys in your account. This GET request returns a comprehensive list of service keys with their metadata and status information.

List Service Keys

curl -X GET <nexla-api-endpoint>/service_keys \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/vnd.nexla.api.v1+json"

Get Service Key Details

Retrieve detailed information about a specific service key to understand its configuration, usage history, and current status. This endpoint provides comprehensive metadata that helps with troubleshooting, security analysis, and operational decision-making. Use this endpoint when you need to investigate specific service key behavior or verify key configuration.

Detail information includes:

• Key metadata: Name, description, creation date, and last modified date
• Usage statistics: Last usage time, usage frequency, and access patterns
• Security status: Current status (active, paused, expired) and security flags
• Permission scope: Organization context and assigned permissions
• Operational data: Associated integrations and dependent systems

API request example:

The following example demonstrates how to retrieve detailed information about a specific service key. Replace <key-id> with the actual ID of the service key you want to inspect.

Get Service Key

curl -X GET <nexla-api-endpoint>/service_keys/<key-id> \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/vnd.nexla.api.v1+json"

Update Service Key

Modify the name and description of a service key to maintain accurate documentation and improve operational clarity. Updating service key metadata helps with key identification, audit compliance, and operational management. This operation is safe and doesn't affect the key's functionality or authentication capabilities.

Update considerations:

• Documentation maintenance: Keep key names and descriptions current
• Operational clarity: Use descriptive names for easier key identification
• Audit compliance: Maintain accurate records for security audits
• Team collaboration: Help team members understand key purposes
• Change tracking: All updates are logged for audit purposes

API request example:

The following example demonstrates how to update a service key's name and description. This PUT request modifies the metadata without affecting the key's authentication capabilities.

Update Service Key

curl -X PUT <nexla-api-endpoint>/service_keys/<key-id> \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Service Key Name",
    "description": "Updated description"
  }'

Rotate Service Key

Generate a new API key while maintaining the same service key ID to enhance security without disrupting existing integrations. Key rotation is a critical security practice that helps mitigate the risk of key compromise while maintaining operational continuity. The rotation process generates a new secret value while preserving the key's metadata and permissions.

Rotation benefits:

• Security enhancement: Replace potentially compromised keys with new ones
• Operational continuity: Maintain the same key ID for seamless integration updates
• Risk mitigation: Reduce exposure window for compromised credentials
• Compliance adherence: Meet security standards requiring regular key rotation
• Automated workflows: Integrate rotation into security automation processes

Rotation process:

• New key generation: Creates a new secret value for the service key
• Metadata preservation: Maintains name, description, and permissions
• Integration updates: Requires updating systems using the old key
• Grace period: Old key remains valid briefly to allow for updates
• Audit logging: All rotation activities are logged for compliance

API request example:

The following example demonstrates how to rotate a service key. This POST request generates a new secret value while maintaining the same key ID and metadata.

Rotate Service Key

curl -X POST <nexla-api-endpoint>/service_keys/<key-id>/rotate \
  -H "Authorization: Bearer <access-token>"

Key rotation generates a new API key while maintaining the same service key ID, allowing for seamless updates without disrupting existing integrations.

Pause Service Key

Temporarily disable a service key to quickly respond to security concerns or operational issues without permanently deleting the key. Pausing a service key immediately stops all authentication attempts while preserving the key's configuration and metadata. This provides a safe way to investigate potential security issues or temporarily halt integrations.

Pause scenarios:

• Security investigation: Temporarily stop access while investigating potential compromise
• Operational issues: Halt integrations during system maintenance or troubleshooting
• Access control: Temporarily restrict access for administrative purposes
• Emergency response: Quick response to security incidents or suspicious activity
• Testing and validation: Pause keys during security testing or validation processes

Pause characteristics:

• Immediate effect: Authentication attempts are immediately rejected
• Reversible action: Keys can be reactivated without loss of configuration
• Metadata preservation: All key information and settings are maintained
• Audit trail: Pause actions are logged with timestamps and user information
• Integration impact: All systems using the key will experience authentication failures

API request example:

The following example demonstrates how to pause a service key. This POST request immediately disables authentication for the specified key while preserving its configuration.

Pause Service Key

curl -X POST <nexla-api-endpoint>/service_keys/<key-id>/pause \
  -H "Authorization: Bearer <access-token>"

Activate Service Key

Re-enable a paused service key to restore normal authentication functionality after resolving security concerns or operational issues. Activation restores the key's full authentication capabilities while maintaining all existing configuration and metadata. This operation should be performed after thorough investigation and resolution of the issues that prompted the pause.

Activation considerations:

• Security verification: Ensure the issues that prompted the pause are resolved
• Integration readiness: Verify that dependent systems are ready for restored access
• Monitoring setup: Ensure proper monitoring is in place for the reactivated key
• Team notification: Notify relevant teams about the key reactivation
• Documentation update: Update any incident documentation with resolution details

Activation process:

• Immediate restoration: Authentication capabilities are restored immediately
• Configuration preservation: All key settings and metadata remain unchanged
• Audit logging: Activation events are logged with timestamps and user information
• Integration testing: Verify that integrations resume normal operation
• Monitoring verification: Confirm that monitoring systems detect the reactivation

API request example:

The following example demonstrates how to reactivate a paused service key. This POST request restores full authentication capabilities for the specified key.

Activate Service Key

curl -X POST <nexla-api-endpoint>/service_keys/<key-id>/activate \
  -H "Authorization: Bearer <access-token>"

Delete Service Key

Permanently remove a service key when it's no longer needed or when security requirements mandate permanent deletion. Deletion is irreversible and immediately terminates all authentication capabilities for the key. This operation should be performed carefully, ensuring that all dependent systems are updated and no critical integrations will be disrupted.

Deletion scenarios:

• Integration termination: Remove keys for discontinued integrations or services
• Security requirements: Permanently delete compromised or unused keys
• Access revocation: Remove access for terminated employees or services
• Cleanup operations: Remove obsolete keys during system cleanup
• Compliance requirements: Meet regulatory requirements for credential deletion

Deletion considerations:

• Integration impact: All systems using the key will immediately lose access
• Irreversible action: Deleted keys cannot be recovered or restored
• Dependent systems: Update all systems using the key before deletion
• Audit requirements: Ensure compliance with audit and retention policies
• Team coordination: Coordinate with all teams using the key

Deletion process:

• Immediate termination: Authentication capabilities are immediately disabled
• Permanent removal: Key data is permanently deleted from the system
• Audit logging: Deletion events are logged with timestamps and user information
• Integration updates: All dependent systems must be updated with new keys
• Documentation cleanup: Update documentation to reflect the deletion

API request example:

The following example demonstrates how to permanently delete a service key. This DELETE request immediately terminates all authentication capabilities and removes the key from the system permanently.

Delete Service Key

curl -X DELETE <nexla-api-endpoint>/service_keys/<key-id> \
  -H "Authorization: Bearer <access-token>"

Security Best Practices

Implementing proper security measures for service keys is crucial for protecting your applications and data. These best practices help ensure that your service keys remain secure while maintaining operational efficiency.

Key Management

Proper key management is the foundation of service key security. These practices help protect your keys from compromise and ensure they're used appropriately.

• Secure Storage: Store service keys in secure credential management systems
• Access Control: Limit who can create and manage service keys
• Regular Rotation: Implement a schedule for key rotation
• Monitoring: Track usage patterns and investigate unusual activity

Usage Guidelines

Following these guidelines helps maintain security while ensuring your service keys serve their intended purpose effectively.

• Principle of Least Privilege: Grant only necessary permissions to service accounts
• Environment Separation: Use different keys for development, staging, and production
• Audit Logging: Monitor all API calls made with service keys
• Incident Response: Have a plan for key compromise scenarios

Production Considerations

Production environments require additional security measures to ensure reliability and protect against real-world threats.

• Key Rotation: Implement automated key rotation processes
• Monitoring: Set up alerts for failed authentication attempts
• Backup Keys: Maintain backup keys for critical systems
• Documentation: Keep detailed records of key usage and purpose

Troubleshooting

When issues arise with service keys, systematic troubleshooting helps identify and resolve problems quickly. These common issues and solutions can help you get back up and running.

Common Issues

Most service key problems fall into these categories. Understanding the root causes helps prevent similar issues in the future.

Authentication Fails

Authentication failures are the most common service key issues and typically occur when the service key is invalid, inactive, or misconfigured. These failures prevent your applications from accessing the Nexla API and can disrupt automated workflows and integrations.

Common causes:

• Invalid key format: Service key contains incorrect characters or formatting
• Key deactivation: Service key has been paused, rotated, or deleted
• Expired credentials: Service key has reached its expiration date
• Network issues: Connectivity problems preventing authentication requests
• API endpoint changes: Using outdated or incorrect API endpoints

Troubleshooting steps:

1. Verify the service key is correct and active
2. Check that the key hasn't been paused or deleted
3. Ensure the key has the necessary permissions

Key Rotation Issues

Key rotation issues occur when the process of replacing an old service key with a new one encounters problems or when systems continue using the old key after rotation. These issues can lead to authentication failures and service disruptions if not handled properly.

Common causes:

• Grace period expiration: Old key becomes invalid before all systems are updated
• Incomplete updates: Some systems still using the old key after rotation
• Configuration errors: New key not properly configured in all systems
• Timing issues: Rotation performed during peak usage periods
• Rollback complications: Difficulty reverting to previous key if needed

Troubleshooting steps:

1. Verify the old key is still valid during rotation
2. Update all systems using the old key immediately
3. Monitor for authentication failures after rotation

Permission Errors

Permission errors occur when a service key is valid but lacks the necessary permissions to access specific resources or perform certain operations. These errors typically manifest as 403 Forbidden responses and indicate that the service key's scope is insufficient for the requested action.

Common causes:

• Insufficient scope: Service key doesn't have required permissions for the operation
• Organization mismatch: Service key belongs to different organization than target resource
• Resource-specific restrictions: Access denied to specific resources or endpoints
• Role limitations: Service key's assigned role doesn't include necessary permissions
• Temporal restrictions: Access limited by time-based or conditional permissions

Troubleshooting steps:

1. Check the service key's organization context
2. Verify the key has access to requested resources
3. Review the key's assigned permissions

Getting Help

If you encounter issues with service keys that cannot be resolved through standard troubleshooting, follow this systematic approach to get the assistance you need. Having the right information ready will help support teams provide faster and more effective solutions.

When to seek help:

• Persistent authentication failures: Issues that continue after basic troubleshooting
• Complex permission problems: Permission errors that require detailed investigation
• Integration disruptions: Service key issues affecting critical business operations
• Security concerns: Suspected key compromise or unauthorized access
• Configuration problems: Complex setup issues requiring expert guidance

Information to gather before contacting support:

1. Check Key Status: Verify the key is active and not expired
2. Review Permissions: Ensure the key has necessary access rights
3. Check Logs: Review authentication logs for error details
4. Contact Support: Reach out to support@nexla.com with specific error messages and key details

Next Steps

• Token Management: Learn about token lifecycle and refresh mechanisms
• Advanced Features: Explore organization context and impersonation
• Security Best Practices: Follow comprehensive security guidelines
• Error Handling: Troubleshoot authentication issues

For comprehensive authentication information, return to the Authentication Overview.