Authentication

Scribeberry uses API key authentication for all API access. There are two types of credentials depending on your use case.

🔑 Need an API key? Go to Console → Settings → API Keys to create or manage your project's keys.

API Keys

Every project gets API keys that start with sk_test_ (sandbox) or sk_live_ (production). These are permanent, full-access keys that should only be used server-side.

Using API Keys

Include your API key in the Authorization header:

curl -H "Authorization: Bearer sk_test_abc123..." \
  https://sandbox.api.scribeberry.com/api/v1/templates

With the SDK:

import { Scribeberry } from '@scribeberry/sdk';
 
const sb = new Scribeberry({ apiKey: 'sk_test_abc123...' });

Key Prefixes

🚫 Danger: Never expose sk_test_ or sk_live_ keys in client-side code, browser JavaScript, mobile apps, or public repositories. These keys have full access to your project.

Temporary Realtime Tokens

For browser-side realtime transcription, you need a short-lived token that's safe to expose to end users. This is the sb_rt_ token.

How it works

┌──────────────┐   1. createToken()    ┌─────────────────┐
│  Your Server │ ─────────────────────▶│  Scribeberry    │
│  (sk_live_)  │ ◀─────────────────────│  API            │
│              │   2. sb_rt_token       │                 │
└──────┬───────┘                        └────────┬────────┘
       │ 3. Pass token                           │
       ▼                                         │
┌──────────────┐   4. WebSocket + audio          │
│  Browser     │ ───────────────────────────────▶│
│  (sb_rt_)    │ ◀───────────────────────────────│
│              │   5. Transcript events           │
└──────────────┘                                  │

1. Your server calls POST /api/v1/realtime/tokens with your API key
2. Scribeberry returns a temporary sb_rt_ token (valid for up to 1 hour)
3. Your server passes the token to the browser
4. The browser connects via WebSocket using the temp token
5. Transcription events stream back in real-time

Creating a Token (Server-Side)

import { Scribeberry } from '@scribeberry/sdk';
 
const sb = new Scribeberry({ apiKey: 'sk_live_...' });
 
// Create a token valid for 1 hour
const { token, wsUrl, expiresAt } = await sb.realtime.createToken({
  expiresInSeconds: 3600,
});
 
// Return to your frontend
res.json({ token, wsUrl, expiresAt });

Using the Token (Browser — Recommended)

The easiest approach: provide a getRealtimeToken callback. The SDK handles token fetching and auto-refresh.

import { Scribeberry } from '@scribeberry/sdk';
 
const sb = new Scribeberry({
  getRealtimeToken: async () => {
    const res = await fetch('/api/realtime-token', { method: 'POST' });
    return res.json(); // { token, expiresAt }
  },
});
 
const session = sb.realtime.transcribe({ language: 'en-US' });
session.on('final', (segment) => console.log(segment.text));

Using the Token (Browser — Manual)

Alternatively, pass a static token directly:

import { Scribeberry } from '@scribeberry/sdk';
 
const sb = new Scribeberry({ apiKey: 'sb_rt_abc123...' });
 
const session = sb.realtime.transcribe({ language: 'en-US' });
session.on('final', (segment) => console.log(segment.text));

Token Restrictions

Temporary tokens have intentional limitations:

Key Management

Rotating Keys

You can rotate API keys from the Scribeberry Console → Settings → API Keys. When you rotate a key:

1. A new key is generated immediately
2. The old key remains valid for a grace period
3. Update your server configuration with the new key
4. The old key is automatically revoked after the grace period

Best Practices

1. Use environment variables — never hardcode keys in source code
2. Separate keys per environment — use sk_test_ for development, sk_live_ for production
3. Use temp tokens for browsers — never send permanent keys to the client
4. Monitor usage — check the Console dashboard for unusual activity
5. Rotate regularly — rotate production keys every 90 days