Skip to main content

Authentication Configurations

Nidra provides comprehensive authentication support for all common auth patterns. This guide covers how to configure authentication for your API requests.

Authentication Types​

Nidra supports:

  • Bearer Token (JWT, OAuth access tokens)
  • Basic Authentication
  • API Key (header or query parameter)
  • OAuth 2.0 (full flow)
  • Custom authentication headers
  • No authentication

Bearer Token​

The most common modern authentication method.

Configuration​

  1. Open your request
  2. Go to the Auth tab
  3. Select "Bearer Token"
  4. Enter your token or use a variable: {{accessToken}}
  5. Save

Example​

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

With Variables​

Store tokens in environments:

Development:

accessToken: dev_token_abc123

Production:

accessToken: prod_token_xyz789

Request:

Auth Type: Bearer Token
Token: {{accessToken}}

Basic Authentication​

Username and password authentication.

Configuration​

  1. Go to the Auth tab
  2. Select "Basic Authentication"
  3. Enter username: {{username}}
  4. Enter password: {{password}}
  5. Save

Nidra automatically encodes credentials to Base64.

Example​

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Best Practices​

  • Store credentials in environment variables
  • Mark password as "secret" to hide it
  • Never commit credentials to version control

API Key​

API keys sent in headers or query parameters.

Header-Based​

  1. Go to the Auth tab
  2. Select "API Key"
  3. Choose location: Header
  4. Enter header name: X-API-Key
  5. Enter value: {{apiKey}}
  6. Save

Query Parameter-Based​

  1. Select "API Key"
  2. Choose location: Query Parameter
  3. Enter parameter name: api_key
  4. Enter value: {{apiKey}}
  5. Save

Examples​

Header:

X-API-Key: your-api-key-here

Query:

GET /users?api_key=your-api-key-here

OAuth 2.0​

Full OAuth 2.0 flow support.

Grant Types Supported​

  • Authorization Code
  • Client Credentials
  • Password Grant
  • Implicit (not recommended, but supported)

Configuration: Client Credentials​

  1. Go to the Auth tab
  2. Select "OAuth 2.0"
  3. Grant Type: Client Credentials
  4. Enter token URL: https://auth.example.com/oauth/token
  5. Enter client ID: {{clientId}}
  6. Enter client secret: {{clientSecret}}
  7. Scope (optional): read write
  8. Click "Get Token"
  9. Save

Configuration: Authorization Code​

For user-based authentication:

  1. Select "OAuth 2.0"
  2. Grant Type: Authorization Code
  3. Enter authorization URL
  4. Enter token URL
  5. Enter client ID and secret
  6. Configure redirect URI
  7. Enter scope
  8. Click "Authorize" (opens browser)
  9. Complete OAuth flow
  10. Token is automatically saved

Token Management​

Nidra handles:

  • Automatic token storage
  • Token refresh (when refresh tokens are provided)
  • Token expiration warnings
  • Manual token refresh

Custom Authentication​

For non-standard auth schemes.

Custom Headers​

Add any custom headers:

  1. Go to the Headers tab
  2. Add header: X-Custom-Auth: {{customToken}}
  3. Save

Multi-Header Authentication​

Some APIs require multiple auth headers:

X-API-Key: {{apiKey}}
X-Signature: {{requestSignature}}
X-Timestamp: {{timestamp}}

Computed Authentication​

Use conduit steps to compute auth values:

Example: AWS Signature V4, custom HMAC signatures, etc.

Collection-Level Authentication​

Set default authentication for all requests in a collection.

  1. Open collection settings
  2. Go to Auth tab
  3. Configure authentication
  4. Save

All requests inherit this auth unless overridden.

Inheritance​

Collection Auth (Bearer Token)
  ├── Request 1 (inherits Bearer)
  ├── Request 2 (inherits Bearer)
  └── Request 3 (overrides with API Key)

Authentication Workflows​

Login Flow with Token Extraction​

Common pattern: Login to get a token, then use it.

  1. Login Request:

    POST {{baseUrl}}/auth/login
    {
      "username": "{{username}}",
      "password": "{{password}}"
    }

  2. Extract Token from response:

    {
      "token": "eyJhbGc..."
    }

    Extract token → save as {{accessToken}}

  3. Use Token in subsequent requests:

    Auth Type: Bearer Token
    Token: {{accessToken}}

Learn about variable extraction →

OAuth Flow in Conduits​

Build a complete OAuth flow:

  1. Get authorization code (may require browser)
  2. Exchange code for access token
  3. Extract access token
  4. Use token for API calls
  5. Refresh token when expired

Multi-Environment Authentication​

Different auth for different environments.

Environment-Specific Credentials​

Development:

apiKey: dev_abc123
username: dev-user
password: dev-pass

Production:

apiKey: prod_xyz789
username: prod-user
password: ******** (secret)

Requests automatically use the correct credentials based on active environment.

Separate Auth Servers​

Staging:

authUrl: https://auth-staging.example.com
clientId: staging_client

Production:

authUrl: https://auth.example.com
clientId: prod_client

Best Practices​

Security​

  • Never hardcode credentials: Always use variables
  • Mark secrets: Use secret variables for passwords/keys
  • Rotate tokens: Update credentials regularly
  • Separate environments: Different credentials per environment
  • Minimal permissions: Use tokens with least privilege

Organization​

  • Set collection defaults: Reduce repetition
  • Use environment variables: Make auth environment-specific
  • Document auth requirements: Add notes about auth flow
  • Test auth failures: Verify error handling

Token Management​

  • Monitor expiration: Set up refresh flows
  • Cache tokens: Reuse tokens across requests (use variables)
  • Handle 401s: Automatically retry after refreshing token

Troubleshooting​

401 Unauthorized​

Check:

  • Is the token/key correct?
  • Has the token expired?
  • Is the header name correct?
  • Is the environment correct?

OAuth Flow Fails​

  • Verify redirect URI matches configuration
  • Check client ID and secret
  • Ensure scope is correct
  • Review authorization server logs

Authentication Not Applied​

  • Check inheritance (collection vs request)
  • Verify the auth tab is configured
  • Ensure variables are resolving correctly

Real-World Example​

Microservices with Different Auth​

Services:

  • User Service: Bearer tokens (OAuth 2.0)
  • Admin API: API Key (header)
  • Legacy API: Basic Auth
  • Public API: No auth

Collections:

User Service Collection:

Auth Type: OAuth 2.0
Grant Type: Client Credentials
Token URL: {{authUrl}}/token
Client ID: {{userServiceClientId}}
Client Secret: {{userServiceClientSecret}}

Admin API Collection:

Auth Type: API Key
Header: X-Admin-Key
Value: {{adminApiKey}}

Legacy API Collection:

Auth Type: Basic Authentication
Username: {{legacyUsername}}
Password: {{legacyPassword}}

Public API Collection:

Auth Type: None

Next Steps​