Authentication & API Access

Overview

VibeIQ provides multiple ways to authenticate and access its API programmatically. This guide covers all authentication methods and access patterns available for integrating external systems with VibeIQ.

API Access Patterns

VibeIQ provides three programmatic access patterns:

• JavaScript/TypeScript SDK - @contrail/sdk
• Java SDK
• HTTPS REST API

All three patterns support the same authentication mechanisms and provide access to the same underlying API functionality.

Authenticating with VibeIQ

Generating an API Key

To authenticate, you'll need an API key. Generate one using the Contrail CLI:

contrail app getApiKey

This generates a key in the format: app:uEL7GCBZ7Xhd4w2z

Note

VibeIQ can provide an access token directly if using the CLI is not preferred.

CLI Authentication

For detailed information on authenticating with the Contrail CLI, including environment variables, configuration files, and platform-specific instructions (macOS/Linux/Windows), see the CLI Authentication Guide.

Authentication Examples

JS SDKcurl

import { login } from '@contrail/sdk';

await login({
  apiKey: 'app:uEL7GCBZ7Xhd4w2z',
  orgSlug: 'your-org-slug'
});

After successful authentication, all SDK functions requiring authentication will work automatically.

curl --location 'https://api.vibeiq.com/prod/api/items/:itemId' \
--header 'X-Api-Key: app:uEL7GCBZ7Xhd4w2z' \
--header 'X-Api-Org: your-org-slug'

For HTTPS REST requests, pass the API key via the X-Api-Key header and organization slug via X-Api-Org header.

Using the JavaScript/TypeScript SDK

Installation

npm install @contrail/sdk

Basic Usage

import { login, Entities } from '@contrail/sdk';

// Authenticate
await login({
  apiKey: process.env.VIBEIQ_API_KEY,
  orgSlug: process.env.VIBEIQ_ORG_SLUG
});

// Use the SDK
const entities = new Entities();

// Get an entity
const item = await entities.get({
  entityName: 'item',
  id: 'item-id-123'
});

// List entities
const items = await entities.list({
  entityName: 'item',
  queryParams: {
    limit: 100
  }
});

// Update an entity
const updatedItem = await entities.update({
  entityName: 'item',
  id: 'item-id-123',
  body: {
    name: 'Updated Name'
  }
});

SDK Resources

• JavaScript SDK Documentation
• Java SDK Documentation
• @contrail/sdk on npm

Using the REST API

Base URL

https://api.vibeiq.com/prod/api

Required Headers

All REST API requests must include:

• X-Api-Key - Your API key
• X-Api-Org - Your organization slug

Common Endpoints

Get an Entity

GET /api/{entityName}/{id}

Example:

curl --location 'https://api.vibeiq.com/prod/api/items/item-id-123' \
--header 'X-Api-Key: your-api-key' \
--header 'X-Api-Org: your-org-slug'

List Entities

GET /api/{entityName}

Example:

curl --location 'https://api.vibeiq.com/prod/api/items?limit=100' \
--header 'X-Api-Key: your-api-key' \
--header 'X-Api-Org: your-org-slug'

Update an Entity

PUT /api/{entityName}/{id}

Example:

curl --location --request PUT 'https://api.vibeiq.com/prod/api/items/item-id-123' \
--header 'X-Api-Key: your-api-key' \
--header 'X-Api-Org: your-org-slug' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Updated Name"
}'

Create an Entity

POST /api/{entityName}

Example:

curl --location 'https://api.vibeiq.com/prod/api/items' \
--header 'X-Api-Key: your-api-key' \
--header 'X-Api-Org: your-org-slug' \
--header 'Content-Type: application/json' \
--data '{
  "name": "New Item",
  "typePath": "item:product"
}'

Delete an Entity

DELETE /api/{entityName}/{id}

Example:

curl --location --request DELETE 'https://api.vibeiq.com/prod/api/items/item-id-123' \
--header 'X-Api-Key: your-api-key' \
--header 'X-Api-Org: your-org-slug'

Authenticating from External Systems

If your integration requires VibeIQ to call your external system (e.g., for webhooks or event workflows), you should provide:

• API endpoint URL - The URL where VibeIQ should send data
• Authentication scheme - Your preferred method (e.g., API keys, Personal Access Tokens, OAuth)
• IP allowlisting - If required, VibeIQ can provide static IP addresses for allowlisting

Webhook Authentication

When VibeIQ sends data to your webhook endpoint, you can secure it using:

1. API Key in Header - VibeIQ can include a custom header with your API key
2. HMAC Signature - VibeIQ can sign requests with a shared secret
3. IP Allowlisting - Restrict access to VibeIQ's IP addresses

Contact VibeIQ support to configure webhook authentication for your integration.

Security Best Practices

API Key Management

• Never commit API keys to source control - Use environment variables or secrets management
• Rotate keys regularly - Generate new keys periodically and revoke old ones
• Use separate keys per environment - Different keys for development, staging, and production
• Limit key scope - Use app-specific keys rather than user keys when possible

Example: Environment Variables

// .env file (never commit this)
VIBEIQ_API_KEY=app:uEL7GCBZ7Xhd4w2z
VIBEIQ_ORG_SLUG=your-org-slug

// In your code
import { login } from '@contrail/sdk';

await login({
  apiKey: process.env.VIBEIQ_API_KEY,
  orgSlug: process.env.VIBEIQ_ORG_SLUG
});

Rate Limiting

VibeIQ APIs are rate-limited to ensure system stability. If you exceed rate limits:

• Implement exponential backoff on errors
• Cache responses when appropriate
• Batch operations when possible
• Contact VibeIQ support to discuss higher limits

Error Handling

Always implement proper error handling for API calls:

import { Entities } from '@contrail/sdk';

async function getItemSafely(itemId: string) {
  try {
    const item = await new Entities().get({
      entityName: 'item',
      id: itemId
    });
    return item;
  } catch (error) {
    if (error.status === 404) {
      console.error(`Item ${itemId} not found`);
    } else if (error.status === 401) {
      console.error('Authentication failed - check API key');
    } else if (error.status === 429) {
      console.error('Rate limit exceeded - implement backoff');
    } else {
      console.error('API error:', error);
    }
    throw error;
  }
}

Testing Your Integration

Using the CLI

The Contrail CLI provides commands for testing API access:

# Test authentication
contrail auth login

# Test API access
contrail entities get --entity-name item --id item-id-123

For more information on CLI authentication methods, including API keys, email/password, and SSO authentication, see the CLI Authentication Guide.

Using Postman or Similar Tools

1. Create a new request
2. Set the method and URL
3. Add headers:
4. X-Api-Key: your-api-key
5. X-Api-Org: your-org-slug
6. Send the request and verify the response

Integration Testing

Create automated tests for your integration:

import { login, Entities } from '@contrail/sdk';

describe('VibeIQ Integration', () => {
  beforeAll(async () => {
    await login({
      apiKey: process.env.VIBEIQ_API_KEY,
      orgSlug: process.env.VIBEIQ_ORG_SLUG
    });
  });

  test('should fetch items', async () => {
    const entities = new Entities();
    const items = await entities.list({
      entityName: 'item',
      queryParams: { limit: 10 }
    });

    expect(items).toBeDefined();
    expect(Array.isArray(items)).toBe(true);
  });

  test('should handle authentication errors', async () => {
    // Test with invalid credentials
    await expect(
      login({
        apiKey: 'invalid-key',
        orgSlug: 'invalid-org'
      })
    ).rejects.toThrow();
  });
});

Troubleshooting

Authentication Errors (401)

• Verify your API key is correct and not expired
• Check that the organization slug matches your account
• Ensure headers are properly formatted

Not Found Errors (404)

• Verify the entity ID exists
• Check that you have access to the entity
• Ensure the entity type is correct

Rate Limit Errors (429)

• Implement exponential backoff
• Reduce request frequency
• Cache responses when possible
• Contact support for higher limits

Network Errors

• Check your internet connection
• Verify the API endpoint URL is correct
• Check for firewall or proxy issues
• Ensure SSL/TLS certificates are valid

Additional Resources

• Assortment Publish Integration
• Change History Polling
• JavaScript SDK Documentation
• Java SDK Documentation
• CLI Automation