Session Tokens

Session access tokens provide temporary authentication for interactive API usage and CLI operations. These tokens are obtained through the Nexla UI or CLI and expire after a configurable interval, typically one hour.

About Session Tokens

Session tokens provide temporary, secure authentication for interactive development and user sessions. Unlike service keys that are permanent, session tokens expire after a configurable interval (typically one hour) and require user interaction for authentication. This design makes them ideal for development workflows, CLI operations, and temporary access scenarios where security and user control are priorities.

Key characteristics of session tokens:

• Temporary authentication: Expire after a configurable interval (typically one hour)
• User-initiated: Require interactive authentication through UI or CLI
• Secure by design: Short lifespan reduces exposure window for security risks
• Easy to obtain: Simple process through web interface or CLI
• Flexible usage: Can be used across multiple platforms and tools

Session tokens are designed for:

• Interactive Development: Manual API testing and exploration
• CLI Operations: Command-line tool usage
• Temporary Access: Short-term authentication needs
• User Sessions: Browser-based application access

Obtaining Session Tokens

Session tokens can be obtained through two convenient methods: the Nexla web interface or the Nexla CLI. Each method offers distinct advantages for different workflows and development environments. Understanding when to use each approach helps ensure efficient token acquisition and optimal user experience.

Obtainment method considerations:

• UI Method: Best for one-time token acquisition and visual confirmation
• CLI Method: Ideal for automated workflows and terminal-based development
• Authentication flow: Both methods use the same underlying authentication process
• Token security: Tokens are displayed securely and should be copied immediately
• Environment flexibility: CLI supports multiple environment configurations

Via the Nexla UI

The most straightforward way to obtain a session token is through the Nexla web interface. This method provides a user-friendly, browser-based approach that's ideal for one-time token acquisition, visual confirmation, and scenarios where you need immediate access to your token. The UI method offers a seamless authentication experience with your organization's Identity Provider.

UI method benefits:

• Visual confirmation: See the token immediately after authentication
• User-friendly interface: No command-line knowledge required
• Secure display: Token is displayed securely with copy-to-clipboard functionality
• Immediate access: No additional configuration or setup required
• Cross-platform compatibility: Works on any device with a web browser

Step-by-step process:

Follow these steps to obtain a session token through the Nexla web interface. The process is straightforward and typically takes only a few minutes to complete:

1. Navigate to Your Instance: Go to your Nexla UI (e.g., https://dataops.nexla.io)
2. Access Token Route: Navigate to /token in your browser
3. Authenticate: Complete authentication with your Identity Provider
4. Copy Token: Copy the displayed access token

The system will automatically redirect you to your organization's preferred Identity Provider for authentication. Upon successful authentication, you'll be presented with a page where you can copy the access token.

Via the Nexla CLI

The Nexla CLI provides convenient methods for obtaining session tokens without leaving your terminal. This approach is ideal for developers who prefer command-line workflows, automated processes, and scenarios where you need to manage multiple environments or integrate token acquisition into your development pipeline.

CLI method benefits:

• Terminal integration: Seamless workflow within your development environment
• Environment management: Support for multiple Nexla environments
• Automation friendly: Can be integrated into scripts and automation tools
• Consistent interface: Same CLI used for other Nexla operations
• Configuration persistence: Environment settings are saved for future use

Environment Configuration

Use this command to set up a new environment or switch between existing ones. Environment configuration is a one-time setup that allows you to work with different Nexla instances (development, staging, production) from the same CLI installation.

CLI Environment Configuration

-> nexla env configure
Available Environments:
         - beta.nexla.io *
NEXLA Environment (ex:dataops.nexla.io): dataops.nexla.io
If your browser didn't open, please go to the following link:

        https://dataops.nexla.io/token

Enter ACCESS TOKEN:

Log into an Existing Environment

Use this command to authenticate with an already configured environment. This is the most common CLI method for obtaining session tokens when you've already set up your environment configuration. The login process will automatically open your browser for authentication and then prompt you to enter the token.

CLI Login

-> nexla env login
Current Environment: dataops.nexla.io
If your browser didn't open, please go to the following link:

        https://dataops.nexla.io/token

Enter ACCESS TOKEN:

CLI authentication process:

The CLI will automatically open your default browser for authentication. If the browser doesn't open automatically, you can manually navigate to the provided URL. After successful authentication, you'll be prompted to enter the access token in your terminal, which will then be securely stored for future CLI operations.

CLI workflow advantages:

• Automated browser opening: Seamless transition from CLI to browser authentication
• Token storage: Automatically stores tokens for future use
• Environment switching: Easy to switch between different Nexla environments
• Session management: CLI handles token expiration and refresh automatically
• Integration capabilities: Can be integrated into development scripts and automation

Using Session Tokens

Once you have a session token, you can use it across different platforms and tools to authenticate with the Nexla API. Session tokens provide a standardized way to authenticate with the Nexla platform, enabling you to interact with APIs, use CLI tools, and integrate with various development environments. Understanding how to properly use session tokens ensures secure and effective authentication across your development workflow.

Usage considerations:

• Cross-platform compatibility: Session tokens work with APIs, CLI, and code examples
• Standard authentication: Bearer token format for consistent authentication
• Security headers: Proper header configuration for secure communication
• Token lifecycle: Understanding expiration and refresh requirements
• Error handling: Proper handling of authentication failures and token expiration

In API Requests

Once you have obtained a session token, include it in subsequent API requests as a Bearer token in the Authorization header. This is the most common way to use session tokens and provides secure authentication for all Nexla API operations. The Bearer token format follows standard OAuth 2.0 conventions and ensures consistent authentication across all API endpoints.

API request requirements:

• Authorization header: Include the token as Bearer <session-token>
• Accept header: Use the proper API version header for compatibility
• HTTPS required: All API requests must use secure connections
• Token validation: Ensure the token is valid and not expired
• Error handling: Implement proper handling for authentication failures

API request example:

The following example demonstrates how to make an authenticated API request using a session token. This curl command shows the proper header format and endpoint structure for accessing Nexla API resources.

API Request with Session Token

curl https://api.nexla.io/teams                      \
  -H "Authorization: Bearer <session-access-token>"  \
  -H "Accept: application/vnd.nexla.api.v1+json"

In CLI Operations

The Nexla CLI automatically uses your stored session token for all operations. This seamless integration eliminates the need to manually pass authentication credentials with each command, making CLI operations more efficient and secure. The CLI handles token management, expiration, and refresh automatically, providing a smooth development experience.

CLI authentication features:

• Automatic token usage: No need to specify tokens with each command
• Secure storage: Tokens are stored securely in your local environment
• Session management: CLI handles token expiration and refresh automatically
• Environment awareness: Different tokens for different Nexla environments
• Error handling: Clear error messages for authentication issues

CLI usage examples:

The following examples demonstrate how the Nexla CLI automatically uses your stored session token for various operations. No additional authentication is required once you've logged in through the CLI.

# List teams (uses stored session token)
nexla teams list

# Create a data source (uses stored session token)
nexla data-sources create --name "My Source" --type "rest"

In Code Examples

The following code examples demonstrate how to use session tokens in different programming languages. These examples show the complete authentication flow and API usage patterns that you can adapt for your own applications. Each example includes proper error handling and follows security best practices.

Implementation considerations:

• Secure storage: Store tokens in environment variables or secure credential managers
• Error handling: Implement comprehensive error handling for authentication failures
• Token validation: Check token validity before making API requests
• Security headers: Use appropriate headers for all API requests
• Connection security: Ensure all requests use HTTPS

Python implementation:

The following Python example demonstrates how to use session tokens with the requests library for making authenticated API calls to the Nexla platform.

Python Example

import requests

headers = {
    'Authorization': 'Bearer <your-session-token>',
    'Accept': 'application/vnd.nexla.api.v1+json'
}

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

JavaScript implementation:

The following JavaScript example demonstrates how to use session tokens with the Fetch API for making authenticated API calls in browser-based or Node.js applications.

JavaScript Example

const headers = {
    'Authorization': 'Bearer <your-session-token>',
    'Accept': 'application/vnd.nexla.api.v1+json'
};

fetch('https://api.nexla.io/teams', { headers })
    .then(response => response.json())
    .then(teams => console.log(teams));

Token Lifecycle

Understanding how session tokens work over time is crucial for maintaining uninterrupted access to the Nexla API. This section explains the token's lifespan and how to manage it effectively.

Expiration

Session tokens expire after a configurable interval, typically one hour. The exact expiration time is specified in the expires_in attribute of the token response. Understanding token expiration is crucial for maintaining uninterrupted access to the Nexla API and preventing authentication failures during your development workflow.

Expiration characteristics:

• Configurable duration: Expiration time can be adjusted based on organization security policies
• Automatic termination: Tokens become invalid immediately upon expiration
• No grace period: Expired tokens cannot be used for API requests
• Clear indication: Expiration time is clearly specified in token response
• Security benefit: Short lifespan reduces exposure window for security risks

Managing expiration:

• Monitor token age: Track how long your token has been active
• Plan ahead: Refresh tokens before they expire to avoid interruptions
• Error handling: Implement proper handling for 401 Unauthorized responses
• Automated refresh: Consider implementing automatic token refresh for long-running processes

Refresh

For long-running operations, you can refresh your session token before it expires. Token refresh allows you to extend your session without requiring re-authentication, maintaining continuous access to the Nexla API. This is particularly useful for development sessions, automated scripts, and scenarios where you need uninterrupted access.

Refresh benefits:

• Continuous access: Maintain uninterrupted API access without re-authentication
• User convenience: Avoid repeated login processes during long sessions
• Automation friendly: Enable automated token management for scripts and tools
• Security maintenance: Extend sessions while maintaining security controls
• Workflow efficiency: Reduce interruptions during development and testing

Refresh considerations:

• Timing: Refresh tokens before they expire to avoid service interruptions
• Response handling: Process the new token from the refresh response
• Error handling: Handle refresh failures gracefully with fallback to re-authentication
• Security: Ensure refresh requests use secure connections and proper headers

API request example:

The following example demonstrates how to refresh a session token. This POST request extends your session by generating a new token with a reset expiration period.

Token Refresh

curl -X POST <nexla-api-endpoint>/token/refresh      \
  -H "Authorization: Bearer <session-access-token>"  \
  -H "Accept: application/vnd.nexla.api.v1+json"     \
  -H "Content-Length: 0"

The refresh response includes a new access token with a reset expiration period.

Invalidation

You can manually invalidate a session token before it expires. Token invalidation immediately terminates the session and renders the token unusable for future API requests. This is an important security practice that should be performed when you're finished with your session or when you suspect the token may have been compromised.

Invalidation scenarios:

• Session completion: Log out when you're finished with your development work
• Security concerns: Invalidate tokens if you suspect unauthorized access
• Environment switching: Clear tokens when switching between different environments
• Token compromise: Immediately invalidate tokens that may have been exposed
• Compliance requirements: Meet organizational policies for session termination

Invalidation benefits:

• Immediate termination: Token becomes invalid instantly upon logout
• Security enhancement: Reduces the window of opportunity for unauthorized access
• Resource cleanup: Frees up server resources associated with the session
• Audit compliance: Provides clear audit trail of session termination
• Access control: Ensures no lingering access after session completion

API request example:

The following example demonstrates how to invalidate a session token. This POST request immediately terminates your session and makes the token unusable for future API requests.

Token Invalidation

curl -X POST <nexla-api-endpoint>/token/logout        \
  -H "Authorization: Bearer <session-access-token>"   \
  -H "Accept: application/vnd.nexla.api.v1+json"      \
  -H "Content-Length: 0"

Best Practices

Following these best practices ensures that your session tokens remain secure and effective throughout your development workflow. These guidelines help prevent common security issues and maintain smooth operations.

Development Workflow

Establishing a consistent workflow for managing session tokens helps ensure smooth development sessions and prevents authentication interruptions.

1. Obtain Token: Get a session token at the start of your development session
2. Store Securely: Keep the token in a secure environment variable or configuration file
3. Monitor Expiration: Set reminders or implement automatic refresh for long sessions
4. Invalidate When Done: Log out when you're finished to ensure security

Security Considerations

Security should always be a top priority when working with authentication credentials. These practices help protect your tokens and maintain the integrity of your development environment.

• Never Commit Tokens: Avoid storing session tokens in source code or configuration files
• Use Environment Variables: Store tokens in environment variables or secure credential stores
• Regular Rotation: Obtain new tokens regularly for enhanced security
• Monitor Usage: Be aware of which systems are using your session token

Error Handling

Proper error handling is essential when working with session tokens to ensure smooth development workflows and quick problem resolution. Understanding common session token errors and their solutions helps you maintain uninterrupted access to the Nexla API and troubleshoot issues efficiently.

Error handling principles:

• Proactive monitoring: Monitor token status and expiration to prevent errors
• Graceful degradation: Handle authentication failures without disrupting user experience
• Clear error messages: Provide meaningful feedback for troubleshooting
• Automatic recovery: Implement automatic token refresh when possible
• Security awareness: Log authentication errors for security monitoring

Common Errors & Solutions

401 Unauthorized

The most common session token error occurs when a token has expired or is invalid. This error typically happens when the token's expiration time has passed or when the token has been manually invalidated.

• Cause: Token has expired or is invalid
• Solution: Obtain a new token through UI or CLI authentication
• Prevention: Monitor token expiration and implement automatic refresh
• Detection: Check for 401 responses in API calls

403 Forbidden

This error occurs when your session token is valid but doesn't have the necessary permissions to access the requested resource. This is a common issue when trying to access resources outside your organization scope or when your role doesn't include the required permissions.

• Cause: Token is valid but lacks required permissions for the requested resource
• Solution: Verify the token has appropriate permissions or contact your administrator
• Prevention: Ensure proper role assignment during token creation
• Detection: Check for 403 responses when accessing specific resources

Token Not Found

This error occurs when your application cannot locate or access the session token. This typically happens due to configuration issues, storage problems, or environment setup issues that prevent the token from being properly stored or retrieved.

• Cause: Token is not properly stored or accessible in your environment
• Solution: Ensure the token is properly stored and accessible in your configuration
• Prevention: Use secure storage methods and verify token persistence
• Detection: Check token storage location and configuration settings

Network Authentication Errors

These errors occur when there are connectivity issues or network configuration problems that prevent successful authentication. These are typically infrastructure-related issues rather than problems with the session token itself.

• Cause: Connectivity issues or network configuration problems
• Solution: Check network connectivity and firewall settings
• Prevention: Implement retry logic with exponential backoff
• Detection: Monitor for connection timeouts and network errors

Invalid Token Format

This error occurs when the session token contains incorrect characters, formatting, or encoding issues. This typically happens when tokens are not properly copied, stored, or transmitted, leading to corruption or malformation.

• Cause: Token contains incorrect characters or formatting
• Solution: Verify token format and ensure proper encoding
• Prevention: Use proper token handling libraries and validation
• Detection: Validate token format before making API requests

Troubleshooting

When issues arise with session tokens, systematic troubleshooting helps identify and resolve problems quickly. These common scenarios and solutions can help you get back up and running with minimal disruption.

Common Issues

Most session token problems fall into these categories. Understanding the root causes and solutions helps you resolve issues quickly and prevent them from recurring.

Browser Authentication Fails

1. Check your Identity Provider credentials
2. Ensure you have access to the Nexla instance
3. Verify your organization membership

CLI Authentication Issues

1. Ensure the CLI is properly configured
2. Check that your browser can access the authentication URL
3. Verify the environment configuration

Token Expires Too Quickly

1. Check your organization's token expiration settings
2. Implement automatic token refresh
3. Consider using service keys for long-running processes

Getting Help

If you continue to experience issues:

1. Check Documentation: Review the Error Handling guide
2. Verify Configuration: Ensure your environment is properly set up
3. Contact Support: Reach out to the Nexla support team with specific error details

Next Steps

• Service Keys: Learn about permanent authentication for automated systems
• Token Management: Understand token lifecycle and refresh mechanisms
• Advanced Features: Explore organization context and impersonation
• Security Best Practices: Follow security guidelines for production use

For comprehensive authentication information, return to the Authentication Overview.