Skip to main content

Overview

All Nexla API and Nexla CLI requests require authentication and must be made over HTTPS. Calls made without authentication or over plain HTTP will fail with HTTP status 401 (Unauthorized).

Choose Your Approach​

Nexla offers two primary authentication approaches designed for different use cases and security requirements. Understanding when to use each method helps you build secure, reliable applications that meet your specific needs.

For Interactive Development​

Choose this approach when you're building, testing, or exploring the API interactively. Session tokens provide the flexibility you need for development work while maintaining security through automatic expiration.

Use cases: API exploration, development testing, manual data operations, debugging Security level: High (automatic expiration, no persistent credentials) Setup complexity: Low (quick setup via UI or CLI)

  1. Get a Session Token: Use the Nexla UI or CLI to obtain a temporary access token
  2. Make API Calls: Include the token in your Authorization header
  3. Refresh as Needed: Tokens expire after ~1 hour, refresh before expiration

For Automated Systems​

Choose this approach when building production systems, CI/CD pipelines, or any automated workflow that needs to run without human intervention. Service keys provide the reliability and security needed for production environments.

Use cases: Production applications, automated workflows, CI/CD pipelines, server-to-server communication Security level: Very high (permanent credentials with rotation capabilities) Setup complexity: Medium (requires careful credential management)

  1. Create a Service Key: Generate a permanent service key through the UI
  2. Authenticate Programmatically: Use the service key to obtain session tokens
  3. Implement Token Management: Handle token refresh and expiration automatically

Authentication Methods​

Nexla provides two complementary authentication methods that work together to support both interactive and automated workflows. Understanding how these methods differ and when to use each one is essential for building secure, reliable applications.

Session Access Tokens​

Temporary authentication for interactive API usage and CLI operations. Perfect for development, testing, and manual API exploration.

Best for: Developers, QA engineers, manual API testing Duration: ~1 hour (configurable) Obtained via: Nexla UI, CLI, or service key exchange Key advantage: Automatic expiration provides security without manual credential management

Service Keys​

Permanent authentication for programmatic access. Designed for server-to-server communication, automated workflows, and integration scenarios.

Best for: Production systems, automated workflows, CI/CD pipelines Duration: Permanent (until rotated or deactivated) Obtained via: Nexla UI or API Key advantage: Reliable, long-term access for automated systems with rotation capabilities

Getting Started​

This section walks you through the essential steps to get up and running with Nexla authentication. Whether you're setting up authentication for the first time or need to verify your configuration, these steps will ensure you can successfully authenticate with the Nexla API.

First-Time Setup​

Follow these steps to get your first authentication credentials working. This setup process ensures you have the right permissions and can successfully authenticate with the Nexla API.

  1. Access Your Nexla Instance: Navigate to your Nexla UI (e.g., https://dataops.nexla.io)
  2. Navigate to Authentication: Go to Settings → Authentication
  3. Choose Your Method: Create a service key or use session-based authentication
  4. Test Your Setup: Make a simple API call to verify authentication

Basic API Call Example​

Once you have your credentials, test them with this simple API call. This example demonstrates the proper format for authenticated requests and helps verify that your authentication is working correctly.

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

Common Scenarios​

Understanding your specific use case helps determine the best authentication approach. Here are the most common scenarios developers encounter and the recommended strategies for each:

Development Environment​

When building and testing applications, you need flexible authentication that can be easily refreshed and doesn't require permanent credentials. This approach prioritizes developer experience and security during the development cycle.

  • Use session tokens for interactive development
  • Refresh tokens manually or implement automatic refresh
  • Test with sample API calls

Production Integration​

Production systems require reliable, secure authentication that can operate autonomously without manual intervention. This approach focuses on security, reliability, and operational efficiency.

  • Create dedicated service keys for each system
  • Implement automatic token refresh
  • Monitor authentication patterns and errors

Multi-User Development​

When working in team environments or building multi-tenant applications, you need authentication that respects organizational boundaries and user permissions while maintaining security.

  • Set up organization context for team collaboration
  • Use impersonation for troubleshooting (admin users only)
  • Implement proper access controls

Need Help?​

If you encounter authentication issues:

  1. Check Token Validity: Ensure your token hasn't expired
  2. Verify Permissions: Confirm you have access to the requested resources
  3. Review Error Messages: Check the Error Handling guide
  4. Contact Support: Reach out to the Nexla support team

For comprehensive authentication documentation, explore the specific topics above or refer to the API Reference for detailed endpoint information.

What's Next?​

Choose the authentication topic that best fits your current needs: