Skip to main content
The Narrative SDK uses API keys for authentication. This guide covers how to configure authentication securely and manage credentials across different environments.

​
Prerequisites

​
Authentication methods

Store your API key in an environment variable to keep it out of source control: 
import { NarrativeApi } from '@narrative.io/data-collaboration-sdk-ts';

const api = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
});
Set the environment variable before running your application: 
export NARRATIVE_API_KEY="your-api-key-here"
node app.js

​
Using a .env file

For local development, use a .env file with a package like dotenv: 
npm install dotenv
Create a .env file in your project root: 
NARRATIVE_API_KEY=your-api-key-here
NARRATIVE_ENVIRONMENT=prod
Load the environment variables in your code: 
import 'dotenv/config';
import { NarrativeApi } from '@narrative.io/data-collaboration-sdk-ts';

const api = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
  environment: process.env.NARRATIVE_ENVIRONMENT || 'prod',
});
Never commit .env files to source control. Add .env to your .gitignore file.

​
Direct configuration

For testing or when credentials are managed externally: 
const api = new NarrativeApi({
  apiKey: 'your-api-key-here',
});
Avoid hardcoding API keys in source code. Use environment variables or a secrets manager in production.

​
Environment selection

The SDK supports multiple environments:
EnvironmentUse case
prodProduction workloads (default)
devDevelopment and testing
Custom URLSelf-hosted or custom deployments
// Production (default)
const prodApi = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
});

// Development
const devApi = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
  environment: 'dev',
});

// Custom URL
const customApi = new NarrativeApi({
  apiKey: process.env.NARRATIVE_API_KEY,
  environment: 'https://custom.narrative.example.com/',
});

​
Verifying authentication

Test your credentials by making a simple API call: 
import { NarrativeApi } from '@narrative.io/data-collaboration-sdk-ts';

async function verifyAuth() {
  const api = new NarrativeApi({
    apiKey: process.env.NARRATIVE_API_KEY,
  });

  try {
    const datasets = await api.getDatasets();
    console.log('Authentication successful!');
    console.log(`Found ${datasets.records.length} datasets`);
  } catch (error) {
    if (error.status === 401) {
      console.error('Authentication failed: Invalid API key');
    } else if (error.status === 403) {
      console.error('Authentication failed: Insufficient permissions');
    } else {
      console.error('Unexpected error:', error);
    }
  }
}

verifyAuth();

​
Updating credentials at runtime

You can change the API key after initialization: 
const api = new NarrativeApi({});

// Set API key later
api.setApiKey('new-api-key');

// Verify the change
console.log('Current key:', api.getApiKey());

​
Security best practices

PracticeDescription
Use environment variablesKeep credentials out of source code
Rotate keys regularlyCreate new keys and revoke old ones periodically
Use minimum permissionsGrant only the permissions needed for the task
Set key expirationConfigure expiration dates for all API keys
Monitor key usageReview access logs for unusual activity

​
Troubleshooting

IssueCauseSolution
401 UnauthorizedInvalid or expired API keyVerify the key is correct and hasn’t expired
403 ForbiddenInsufficient permissionsCheck the key’s permissions in Settings > API Keys
undefined API keyEnvironment variable not setEnsure the variable is exported in your shell
Key not working in CI/CDVariable not configuredAdd the secret to your CI/CD environment

​
Related content

API Keys

Create and manage API keys

Configuration Reference

Complete configuration options

Error Handling

Handle authentication errors gracefully

Permissions Reference

All available permission resources and access levels