raqeb

Raqeb Node.js SDK

Official Node.js/TypeScript SDK for Raqeb Database PAM and Secrets Management.

Installation

npm install raqeb
# or
yarn add raqeb

Quick Start

TypeScript

import { RaqebClient } from 'raqeb';

// Initialize client
const client = new RaqebClient({
  apiKey: 'sa_your_api_key_here'
});

// Get a secret
const secret = await client.getSecret('secret-id');
console.log(`Secret value: ${secret.value}`);

// Get temporary database credentials
const creds = await client.getDatabaseCredentials('db-id', {
  ttlHours: 4,
  accessLevel: 'read-only'
});

console.log(`Username: ${creds.username}`);
console.log(`Password: ${creds.password}`);
console.log(`Expires: ${creds.expiresAt}`);

// Revoke credentials when done
await client.revokeLease(creds.leaseId);

JavaScript

const { RaqebClient } = require('raqeb');

const client = new RaqebClient({
  apiKey: 'sa_your_api_key_here'
});

// Use async/await
(async () => {
  const secret = await client.getSecret('secret-id');
  console.log(secret.value);
})();

Usage Examples

Secrets Management

import { RaqebClient } from 'raqeb';

const client = new RaqebClient({ apiKey: process.env.RAQEB_API_KEY });

// Retrieve a secret
const secret = await client.getSecret('api-key-prod');
const apiKey = secret.value;

// Use the secret
import axios from 'axios';
const response = await axios.get('https://api.example.com/data', {
  headers: { Authorization: `Bearer ${apiKey}` }
});

Database Access with PostgreSQL

import { RaqebClient } from 'raqeb';
import { Client } from 'pg';

const raqeb = new RaqebClient({ apiKey: process.env.RAQEB_API_KEY });

// Get temporary credentials
const creds = await raqeb.getDatabaseCredentials('prod-postgres', {
  ttlHours: 2,
  accessLevel: 'read-only'
});

// Connect to database
const db = new Client({
  host: 'db.example.com',
  port: 5432,
  database: 'myapp',
  user: creds.username,
  password: creds.password,
});

try {
  await db.connect();
  const result = await db.query('SELECT * FROM users LIMIT 10');
  console.log(result.rows);
} finally {
  await db.end();
  // Revoke credentials
  await raqeb.revokeLease(creds.leaseId);
}

Database Access with MySQL

import { RaqebClient } from 'raqeb';
import mysql from 'mysql2/promise';

const raqeb = new RaqebClient({ apiKey: process.env.RAQEB_API_KEY });

const creds = await raqeb.getDatabaseCredentials('prod-mysql', {
  ttlHours: 1,
  accessLevel: 'read-write'
});

const connection = await mysql.createConnection({
  host: 'db.example.com',
  user: creds.username,
  password: creds.password,
  database: 'myapp'
});

try {
  const [rows] = await connection.execute('SELECT * FROM products');
  console.log(rows);
} finally {
  await connection.end();
  await raqeb.revokeLease(creds.leaseId);
}

API Key Management

import { RaqebClient } from 'raqeb';

const client = new RaqebClient({ apiKey: process.env.RAQEB_API_KEY });

// List API keys
const keys = await client.listAPIKeys();
keys.forEach(key => {
  console.log(`${key.name}: ${key.keyPrefix}...`);
  console.log(`  Active: ${key.isActive}`);
  console.log(`  Last used: ${key.lastUsedAt || 'Never'}`);
});

// Create new API key
const newKey = await client.createAPIKey({
  name: 'CI/CD Pipeline',
  scopes: ['secrets:read', 'databases:read'],
  description: 'Key for automated deployments'
});
console.log(`New API Key: ${newKey.apiKey}`); // Save this!

// Delete API key
await client.deleteAPIKey('key-id');

Error Handling

import {
  RaqebClient,
  AuthenticationError,
  PermissionError,
  NotFoundError,
  RaqebError
} from 'raqeb';

const client = new RaqebClient({ apiKey: process.env.RAQEB_API_KEY });

try {
  const secret = await client.getSecret('secret-id');
  console.log(secret.value);
  
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid or expired API key');
  } else if (error instanceof PermissionError) {
    console.error('Insufficient permissions - check API key scopes');
  } else if (error instanceof NotFoundError) {
    console.error('Secret not found');
  } else if (error instanceof RaqebError) {
    console.error(`API error: ${error.message}`);
  } else {
    console.error('Unexpected error:', error);
  }
}

Express.js Middleware

import express from 'express';
import { RaqebClient } from 'raqeb';

const app = express();
const raqeb = new RaqebClient({ apiKey: process.env.RAQEB_API_KEY });

// Middleware to inject database credentials
app.use(async (req, res, next) => {
  try {
    const creds = await raqeb.getDatabaseCredentials('prod-db', {
      ttlHours: 1,
      accessLevel: 'read-only'
    });
    
    req.dbCreds = creds;
    
    // Cleanup after response
    res.on('finish', async () => {
      await raqeb.revokeLease(creds.leaseId);
    });
    
    next();
  } catch (error) {
    res.status(500).json({ error: 'Failed to get database credentials' });
  }
});

app.get('/users', async (req, res) => {
  // Use req.dbCreds to connect to database
  // ...
});

API Reference

RaqebClient

Constructor

new RaqebClient(options: RaqebClientOptions)

Options:

• apiKey (string, required): Service account API key
• baseUrl (string, optional): Base URL for Raqeb API (default: https://app.raqeb.cloud/api/v1)
• timeout (number, optional): Request timeout in milliseconds (default: 30000)

Methods

getSecret(secretId: string): Promise<Secret>

Retrieve a secret value.

getDatabaseCredentials(databaseId: string, options?: DatabaseCredentialsOptions): Promise<DatabaseCredentials>

Generate temporary database credentials.

Options:

• ttlHours (number): Time to live in hours (default: 4)
• accessLevel ('read-only' | 'read-write' | 'admin'): Access level (default: 'read-only')

revokeLease(leaseId: string): Promise<void>

Revoke a dynamic secret lease.

listAPIKeys(): Promise<APIKey[]>

List user's API keys.

createAPIKey(data: APIKeyCreate): Promise<APIKey & { apiKey: string }>

Create a new API key.

deleteAPIKey(keyId: string): Promise<void>

Delete an API key.

TypeScript Support

This SDK is written in TypeScript and includes full type definitions.

import { RaqebClient, DatabaseCredentials, Secret } from 'raqeb';

const client: RaqebClient = new RaqebClient({ apiKey: 'sa_key' });
const creds: DatabaseCredentials = await client.getDatabaseCredentials('db-id');
const secret: Secret = await client.getSecret('secret-id');

Environment Variables

import { RaqebClient } from 'raqeb';

const client = new RaqebClient({
  apiKey: process.env.RAQEB_API_KEY!,
  baseUrl: process.env.RAQEB_BASE_URL
});

Best Practices

• Use environment variables - Never hardcode API keys
• Minimal scopes - Only grant necessary permissions
• Short TTLs - Use shortest time needed for database access
• Always revoke - Clean up credentials when done
• Error handling - Catch and handle SDK exceptions
• TypeScript - Leverage type safety for better development experience

License

MIT License - see LICENSE file for details

Support

• Documentation: https://docs.raqeb.cloud
• Email: [e-mail]
• GitHub: https://github.com/raqeb/nodejs-sdk