Credentials API

Server-side AES-256-GCM encryption/decryption for platform credentials

Overview

The Credentials API provides secure, server-side encryption for sensitive creator credentials (API keys, passwords, session cookies). All encryption uses AES-256-GCM with keys that never leave the server.

Key Features:

• Server-side encryption (clients never handle encryption keys)
• Multiple credential types: platform connections, download credentials, session cookies
• Directus JWT authentication for user-facing endpoints
• Shared secret authentication for server-to-server operations

Endpoint Categories

1. Platform Connections

User-facing endpoints for managing creator platform credentials (Instagram, TikTok, etc.)

2. Download Credentials

YouTube-DL/yt-dlp compatible credentials (passwords, Netscape cookies)

3. Platform Sessions

Browser extension cookie capture for HITL (Human-in-the-Loop) authentication

---

Platform Connections

POST /api/credentials/create-profile

Create or update a creator profile with encrypted credentials.

Authentication: Directus JWT (Bearer token)

platform · string · required

Platform identifier (e.g., instagram, tiktok, youtube)

platform_username · string

Creator’s username on the platform (optional)

credentials · object · required

Platform-specific credentials object (will be encrypted server-side)

Example for Instagram:

{
  "username": "creator123",
  "password": "securepass",
  "session_id": "abc123xyz"
}

Response:

success · boolean

Operation success status

id · string

UUID of the created/updated platform_connections record

updated · boolean

true if existing connection was updated, false if new record created

Example Request:

curl -X POST http://localhost:3001/api/credentials/create-profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "platform_username": "fitcreator99",
    "credentials": {
      "username": "fitcreator99",
      "password": "MySecurePass123!",
      "session_id": "abc123sessionxyz"
    }
  }'

Response:

{
  "success": true,
  "id": "d3f21c8e-4a5b-4c9d-8e7f-1a2b3c4d5e6f",
  "updated": false
}

POST /api/credentials/update-profile-creds

Update encrypted credentials on an existing creator profile the user owns.

Authentication: Directus JWT (Bearer token)

creator_profile_id · string · required

UUID of the platform_connections record to update

credentials · object · required

New credentials object (replaces existing encrypted data)

platform_username · string

Update the platform username (optional)

Example Request:

curl -X POST http://localhost:3001/api/credentials/update-profile-creds \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "creator_profile_id": "d3f21c8e-4a5b-4c9d-8e7f-1a2b3c4d5e6f",
    "credentials": {
      "username": "fitcreator99",
      "password": "NewSecurePass456!",
      "session_id": "newSessionXYZ789"
    }
  }'

Response:

{
  "success": true,
  "id": "d3f21c8e-4a5b-4c9d-8e7f-1a2b3c4d5e6f"
}

---

Server-to-Server Endpoints

These endpoints require the X-RBAC-SYNC-SECRET header. Never call from client code.

POST /api/credentials/store

Encrypt and save credentials to Directus platform_connections table.

Authentication: X-RBAC-SYNC-SECRET header

creatorProfileId · string · required

UUID of the platform_connections record

credentials · object · required

Credentials object to encrypt and store

Example Request:

curl -X POST http://localhost:3001/api/credentials/store \
  -H "X-RBAC-SYNC-SECRET: your-secret-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "creatorProfileId": "d3f21c8e-4a5b-4c9d-8e7f-1a2b3c4d5e6f",
    "credentials": {
      "api_key": "sk-proj-abc123xyz",
      "refresh_token": "refresh_token_value"
    }
  }'

Response:

{
  "success": true,
  "creatorProfileId": "d3f21c8e-4a5b-4c9d-8e7f-1a2b3c4d5e6f",
  "updated": "d3f21c8e-4a5b-4c9d-8e7f-1a2b3c4d5e6f"
}

POST /api/credentials/reveal

Decrypt and return credentials for a creator profile.

Authentication: X-RBAC-SYNC-SECRET header

creatorProfileId · string · required

UUID of the platform_connections record

success · boolean

Operation success status

creatorProfileId · string

UUID of the profile

credentials · object

Decrypted credentials object

Example Request:

curl -X POST http://localhost:3001/api/credentials/reveal \
  -H "X-RBAC-SYNC-SECRET: your-secret-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "creatorProfileId": "d3f21c8e-4a5b-4c9d-8e7f-1a2b3c4d5e6f"
  }'

Response:

{
  "success": true,
  "creatorProfileId": "d3f21c8e-4a5b-4c9d-8e7f-1a2b3c4d5e6f",
  "credentials": {
    "api_key": "sk-proj-abc123xyz",
    "refresh_token": "refresh_token_value"
  }
}

---

Download Credentials (yt-dlp)

POST /api/credentials/create-download-cred

Create credentials for yt-dlp/youtube-dl authentication (password or cookies).

Authentication: Directus JWT (Bearer token)

platform · string · required

Platform identifier (e.g., youtube, instagram)

creator_profile_id · string · required

UUID of the associated platform_connections record

auth_type · string · required

Either password or cookies

username · string

Platform username (optional for cookies auth)

credentials · object · required

For password auth:

{ "password": "mypassword" }

For cookies auth:

{ "cookies_netscape": "# Netscape HTTP Cookie File\n.youtube.com\tTRUE\t/\t..." }

display_name · string

Human-readable name for this credential set (optional)

Example Request (Password Auth):

curl -X POST http://localhost:3001/api/credentials/create-download-cred \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "youtube",
    "creator_profile_id": "d3f21c8e-4a5b-4c9d-8e7f-1a2b3c4d5e6f",
    "auth_type": "password",
    "username": "[e-mail]",
    "credentials": {
      "password": "MyYouTubePassword123"
    },
    "display_name": "My YouTube Channel"
  }'

Response:

{
  "success": true,
  "id": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
}

POST /api/credentials/reveal-download-cred

Decrypt download credentials (server-to-server only).

Authentication: X-RBAC-SYNC-SECRET header

id · string · required

UUID of the download_credentials record

Example Request:

curl -X POST http://localhost:3001/api/credentials/reveal-download-cred \
  -H "X-RBAC-SYNC-SECRET: your-secret-key-here" \
  -H "Content-Type: application/json" \
  -d '{"id": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6"}'

Response:

{
  "success": true,
  "id": "a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
  "platform": "youtube",
  "auth_type": "password",
  "credentials": {
    "password": "MyYouTubePassword123"
  }
}

---

Platform Sessions (Cookie Capture)

POST /api/credentials/store-platform-session

Store browser cookies captured via extension (HITL authentication).

Authentication: Directus JWT (Bearer token)

creator_profile_id · string · required

UUID of the platform_connections record

platform · string · required

Platform identifier (e.g., instagram, tiktok)

cookies · array · required

Array of browser cookie objects:

[
  {
    "name": "sessionid",
    "value": "abc123xyz",
    "domain": ".instagram.com",
    "path": "/",
    "expires": 1735689600,
    "httpOnly": true,
    "secure": true
  }
]

user_agent · string

Browser user agent string (optional)

expires_at · string

ISO 8601 expiry timestamp (optional)

Example Request:

curl -X POST http://localhost:3001/api/credentials/store-platform-session \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "creator_profile_id": "d3f21c8e-4a5b-4c9d-8e7f-1a2b3c4d5e6f",
    "platform": "instagram",
    "cookies": [
      {
        "name": "sessionid",
        "value": "123456789%3AabcXYZ%3A28",
        "domain": ".instagram.com",
        "path": "/",
        "expires": 1735689600,
        "httpOnly": true,
        "secure": true
      }
    ],
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  }'

Response:

{
  "success": true,
  "id": "session-uuid-123",
  "platform": "instagram",
  "cookie_count": 1
}

POST /api/credentials/get-platform-session

Retrieve decrypted session cookies (server-to-server only).

Authentication: X-RBAC-SYNC-SECRET header

creator_profile_id · string · required

UUID of the platform_connections record

platform · string · required

Platform identifier

Example Request:

curl -X POST http://localhost:3001/api/credentials/get-platform-session \
  -H "X-RBAC-SYNC-SECRET: your-secret-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "creator_profile_id": "d3f21c8e-4a5b-4c9d-8e7f-1a2b3c4d5e6f",
    "platform": "instagram"
  }'

Response:

{
  "success": true,
  "id": "session-uuid-123",
  "platform": "instagram",
  "cookies": [
    {
      "name": "sessionid",
      "value": "123456789%3AabcXYZ%3A28",
      "domain": ".instagram.com",
      "path": "/",
      "expires": 1735689600,
      "httpOnly": true,
      "secure": true
    }
  ],
  "captured_at": "2026-01-15T10:30:00.000Z",
  "expires_at": "2026-12-31T23:59:59.000Z",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}

POST /api/credentials/revoke-platform-session

Mark a platform session as revoked (disables cookie usage).

Authentication: Directus JWT (Bearer token)

id · string · required

UUID of the platform_sessions record

Example Request:

curl -X POST http://localhost:3001/api/credentials/revoke-platform-session \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"id": "session-uuid-123"}'

Response:

{
  "success": true,
  "id": "session-uuid-123"
}

---

Encryption Details

All credential encryption uses the encryptJSON() and decryptJSON() utilities (server/utils/credentialsCrypto.js):

• Algorithm: AES-256-GCM
• Key derivation: Server-side environment variable (never exposed)
• IV: Randomly generated per encryption operation
• Output format: Base64-encoded iv:authTag:ciphertext

Security guarantees:

• Encryption keys never leave the server
• Clients never handle plaintext encryption keys
• Each credential has unique IV (no key reuse)
• Authentication tags prevent tampering

Error Handling

Common error responses:

Missing credentials:

{
  "success": false,
  "error": "No encrypted_credentials found"
}

Unauthorized (invalid secret):

{
  "success": false,
  "error": "Unauthorized"
}

Forbidden (not profile owner):

{
  "success": false,
  "error": "Forbidden"
}

Directus error (upstream):

{
  "success": false,
  "error": "Directus 400 /items/platform_connections/invalid-uuid: {\"errors\":[{\"message\":\"Invalid UUID\"}]}"
}