N8N Setup

Step-by-step instructions for connecting your N8N instance to Ragtime using N8N’s built-in credential system. Once configured, any workflow can reuse the credential without repeating auth setup.

Overview

N8N workflows that call Ragtime’s API (Ingest, Analytics, etc.) need an authenticated credential. Instead of hardcoding the API key into every HTTP Request node, you create a reusable credential in N8N. This guide walks you through that process using N8N’s “Add new credential” dialog.

Prerequisites

1. A running N8N instance (self-hosted or N8N Cloud).
2. A Ragtime API key — create one in Dashboard → Assistant → API Keys (see the API Keys guide). Copy the full key (starts with rt_live_) — it’s shown only once.
3. Your Ragtime instance URL (e.g. https://your-ragtime-instance.com).
4. Your Project ID — found on the Dashboard → Assistant → API Keys tab. For ingest endpoints you’ll also need a Library ID, which you can retrieve via the List Libraries endpoint.

Creating the Credential

N8N supports several credential types for HTTP requests. The simplest option for Ragtime is Bearer Auth, which only requires your API key token.

Option A: Bearer Auth (recommended)

1. In your N8N instance, open any workflow (or create a new one).
2. Add an HTTP Request node to the canvas.
3. In the node parameters, set Authentication to Generic Credential Type.
4. Under Generic Auth Type, select Bearer Auth.
5. Click the Credential dropdown and select “Create new Bearer Auth credential”.
6. In the dialog, enter your Ragtime API key in the Token field — paste the full key starting with rt_live_. Nothing else is needed; N8N automatically sends it as an Authorization: Bearer <token> header.
7. Click Save.

Option B: Header Auth

If you prefer full control over the header, use Header Auth instead:

1. Follow steps 1–3 above, but select Header Auth as the Generic Auth Type.
2. Click “Create new Header Auth credential”.
3. The dialog shows two fields:
   • Name — the HTTP header name to send. Enter Authorization (exactly, case-sensitive).
   • Value — the header value. Enter Bearer rt_live_YOUR_KEY_HERE — that’s the word Bearer, a single space, then your full API key.
4. Leave Allowed HTTP Request Domains set to All (or restrict it to your Ragtime instance URL for extra security).
5. Click Save.

Both options produce the same HTTP header. Bearer Auth is simpler because you don’t need to type Authorization or Bearer yourself — N8N handles that for you.

Alternative: Using the Credential Picker

You can also create credentials from N8N’s global credential manager without opening a workflow first:

1. Go to Credentials in the left sidebar (or Settings → Credentials).
2. Click “Add new credential”.
3. A dialog appears: “Select an app or service to connect to”. Type Bearer Auth (or Header Auth) in the search box and select it.
4. Fill in the fields as described above for your chosen option.
5. Click Save.

This credential will now appear in the dropdown of any HTTP Request node that uses the matching auth type.

For text-native sources like Slack threads or form submissions, you can post raw content directly to the ingest endpoint. That means a Code node can format Markdown or plain text and send it straight to Ragtime without staging the payload in R2, S3, or another object store first.

Use this split as a rule of thumb in N8N workflows:

• Use url for binary files (PDF, DOCX) that need download/extraction.
• Use content for text-native payloads you already have in the workflow (Slack summaries, CRM notes, webhook bodies, form submissions).

Example HTTP Request node body for URL-based ingest:

{
   "url": "{{ $json.fileUrl }}",
   "fileName": "{{ $json.fileName }}",
   "externalId": "{{ $json.docId }}"
}

Example HTTP Request node body for direct-content ingest:

{
   "content": "{{ $json.markdown }}",
   "contentType": "text/markdown",
   "fileName": "{{ $json.title }}",
   "externalId": "{{ $json.docId }}"
}

For full request-body rules and limits, see the Ingest API guide.

Using the Credential in a Workflow

Once the credential exists, attach it to any HTTP Request node that talks to Ragtime:

1. Add or open an HTTP Request node.
2. Set Method to the appropriate verb (POST for ingest, GET for analytics).
3. Set URL to the Ragtime endpoint, e.g.: https://your-ragtime-instance.com/api/v1/projects/{projectId}/libraries/{libraryId}/ingest
4. Set Authentication → Generic Credential Type → Bearer Auth (or Header Auth if you used that option).
5. Pick your “Ragtime API Key” credential from the dropdown.
6. Configure the request body or query parameters as needed (see the Ingest API or Analytics API guides).

That’s it — N8N will automatically inject the Authorization: Bearer rt_live_... header into every request made by this node.

Setting Up Webhook Verification (Optional)

If your workflow receives webhooks from Ragtime (instead of calling Ragtime), you may want to verify the X-Ragtime-Signature header. In N8N:

1. Use a Webhook trigger node to receive incoming requests.
2. Add a Code node after the Webhook node to verify the signature:

// Code node: Verify Ragtime webhook signature
const crypto = require('crypto');

const secret = $env.RAGTIME_WEBHOOK_SECRET; // Set in N8N environment variables
const body = JSON.stringify($input.first().json.body);
const signature = $input.first().json.headers['x-ragtime-signature'];

const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(body).digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
 throw new Error('Invalid webhook signature');
}

return $input.all();

Store your webhook signing secret in N8N’s environment variables (Settings → Variables or via N8N_VARIABLES) rather than hardcoding it in the workflow.

Tips & Best Practices

• Name credentials clearly — e.g. “Ragtime API Key (Production)” vs “Ragtime API Key (Staging)” if you have multiple environments.
• Use N8N environment variables for secrets. In the Bearer Token (or Header Value) field, you can reference variables: ={{$env.RAGTIME_API_KEY}}
• One credential per environment — don’t mix production and staging keys in the same credential.
• Test with the preview URL first — Ragtime’s isLive flag is false for preview traffic, so you can safely test without polluting production analytics.
• Check your scopes — make sure your API key has the right scopes (ingest, analytics:read) for the endpoints you intend to call.

Troubleshooting

• 401 Unauthorized: If using Bearer Auth, verify the token is the full key (starting with rt_live_). If using Header Auth, ensure the Name is Authorization and the Value starts with Bearer (with a space). In both cases, check the key hasn’t been revoked in Dashboard -> API Keys.
• 403 Forbidden: The API key is valid but missing the required scope. Edit the key’s scopes in Dashboard -> API Keys, or create a new key with the correct scopes.
• Credential not showing in dropdown: Make sure the HTTP Request node’s Authentication is set to Generic Credential Type -> the same auth type you created (Bearer Auth or Header Auth). Credentials only appear under their matching type.
• N8N says “Could not connect”: Verify that your N8N instance can reach your Ragtime instance’s URL. If self-hosting both, ensure they are on the same network or that firewalls allow the connection.
• Webhook events not arriving: Check the webhook delivery history in Dashboard -> Webhooks -> History. Verify the webhook URL in Ragtime matches the N8N webhook trigger URL exactly (including trailing slashes).