> ## Documentation Index
> Fetch the complete documentation index at: https://docs.altitut-sma-center.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Altitut: API Keys, Services, and Platforms

> Set up API keys, connect social accounts, configure Firebase, and optionally enable the Telegram bot so every Altitut feature works end-to-end.

Before you can use Altitut's AI, publishing, and data features, you need to supply a set of API credentials and connect the external services the platform depends on. All configuration is done through environment variables — nothing sensitive ever reaches the browser. This page covers every configuration area in the order you should set them up.

## Required API Keys

Altitut reads credentials from environment variables at startup. Copy `.env.example` to `.env` at the root of your project and fill in the values below.

```bash theme={null}
cp .env.example .env
```

Then open `.env` and set the following:

```bash .env theme={null}
# ── AI & Embeddings ──────────────────────────────────────────
OPENAI_API_KEY=sk-...

# ── Competitor Discovery & Research ─────────────────────────
EXA_API_KEY=exa-...

# ── Instagram Scraping ───────────────────────────────────────
APIFY_TOKEN=apify_...

# ── Social Publishing ────────────────────────────────────────
UPLOAD_POST_API_KEY=up-...
UPLOAD_POST_PROFILE=your-profile-name

# ── Telegram Bot (optional) ──────────────────────────────────
TELEGRAM_BOT_TOKEN=123456:ABC-...
TELEGRAM_WEBHOOK_SECRET=your-random-hex-secret
```

> [!NOTE]
>
> **OPENAI\_API\_KEY**, **EXA\_API\_KEY**, **APIFY\_TOKEN**, **UPLOAD\_POST\_API\_KEY**, and **UPLOAD\_POST\_PROFILE** are all required for core functionality. **TELEGRAM\_BOT\_TOKEN** and **TELEGRAM\_WEBHOOK\_SECRET** are optional — omitting them simply disables the Telegram bot integration without affecting any other feature.

> [!WARNING]
>
> Never commit your `.env` file to version control or expose these keys on the client side. All API calls that use these credentials are made from the backend. Add `.env` to your `.gitignore` immediately if it is not there already.

> [accordion] OPENAI\_API\_KEY — AI inference and vector embeddings
>
> Altitut uses OpenAI for all generative AI features: the synthesis passes in Competitor Scout, AI Copilot chat responses, Content Pack generation, and Auto-Post caption generation. It also uses OpenAI's embedding models to power the RAG retrieval that the AI Copilot relies on.
>
> You can obtain an API key from the [OpenAI platform](https://platform.openai.com/api-keys). Make sure your account has access to the `gpt-4o-mini` model before setting up Altitut.

> [accordion] EXA\_API\_KEY — Competitor discovery and research
>
> Exa AI powers the **Discover** and **Research** stages of the Competitor Scout pipeline. In the Discover stage, Exa performs a semantic search to surface competitors matching your query. In the Research stage, Exa retrieves deep contextual information about each competitor's brand positioning and messaging.
>
> Get your API key from the [Exa dashboard](https://dashboard.exa.ai).

> [accordion] APIFY\_TOKEN — Instagram scraping
>
> Apify runs the **Website** and **Social** stages of the Competitor Scout pipeline. It crawls each competitor's public website for content and maps their Instagram presence, including reels and post metadata.
>
> Get your token from the [Apify console](https://console.apify.com/account/integrations).

> [accordion] UPLOAD\_POST\_API\_KEY and UPLOAD\_POST\_PROFILE — Social publishing
>
> The Upload-Post API handles all social media publishing. Altitut uses it in the Auto-Post Composer to deliver posts to LinkedIn, Facebook, and Instagram. It also provides the list of connected accounts shown in the Destinations step.
>
> * **UPLOAD\_POST\_API\_KEY** — your API key from the Upload-Post dashboard.
> * **UPLOAD\_POST\_PROFILE** — the Upload-Post profile name where your social accounts are connected (e.g. `my-brand`).
>
> Get your key from the [Upload-Post dashboard](https://app.upload-post.com) under **Settings → API**.

***

## Social Platform Connection

Altitut publishes to social platforms through the **Upload-Post** service rather than direct OAuth integrations. This means you manage account connections in the Upload-Post dashboard — not inside Altitut itself.

**1. Create a Profile in Upload-Post**

Log in at [app.upload-post.com](https://app.upload-post.com) and create a **Profile** that matches the value you set for `UPLOAD_POST_PROFILE` in your `.env` file (for example, `my-brand`).

**2. Add Connected Accounts**

Inside your profile, navigate to **Connected Accounts** and click **Add Account**. Authenticate with LinkedIn, Facebook, and/or Instagram through each platform's OAuth flow.

> [!NOTE]
>
> For Facebook, connect a **Facebook Page** you administer (not a personal profile). For Instagram, connect a **Business or Creator** account. For LinkedIn, connect a personal profile or a company page where you have admin access.

**3. Verify in Altitut**

Start your development server and open the **Auto-Post Composer** in Altitut. Advance to the **Destinations** step. All accounts you connected in the previous step should appear automatically. Altitut fetches the account list from Upload-Post on each composer session.

> [!NOTE]
>
> If a connected account does not appear in the Destinations step, verify that your `UPLOAD_POST_API_KEY` and `UPLOAD_POST_PROFILE` match the Upload-Post account and profile where you added the social account. Keys and profiles are scoped per Upload-Post account.

***

## Telegram Bot (Optional)

The Telegram bot lets your team send Instagram reel URLs to a bot and receive a generated Content Pack automatically — without opening the Altitut dashboard.

**1. Create a Bot with BotFather**

Open Telegram and start a conversation with [@BotFather](https://t.me/BotFather). Send `/newbot`, follow the prompts, and copy the bot token you receive.

**2. Add the Token to Your Environment**

Add the token (and an optional webhook secret) to your `.env` file:

```bash .env theme={null}
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_WEBHOOK_SECRET=your-random-hex-secret
```

The webhook secret is optional but recommended — it lets Altitut verify that incoming webhook requests genuinely originate from Telegram.

**3. Deploy and Register the Webhook**

Deploy your app to a public HTTPS URL, then register the webhook using the built-in npm script:

```bash theme={null}
npm run telegram:webhook -- https://your-app.vercel.app
```

> [!NOTE]
>
> Telegram requires a **publicly reachable HTTPS URL** for webhooks. During local development, use a tunneling tool such as [ngrok](https://ngrok.com) to expose your local server.

**4. Test the Integration**

Send an Instagram reel URL to your bot in Telegram. Within a few seconds, Altitut should respond with a confirmation that a Content Pack is being generated. The finished pack will appear in the **Content Packs** section of the dashboard.

> [!WARNING]
>
> Treat your `TELEGRAM_BOT_TOKEN` with the same care as any other API key. Anyone who holds this token can send messages as your bot. Rotate it immediately via BotFather if you suspect it has been compromised.

***

## Firebase (Firestore and Storage)

Altitut uses two Firebase services:

* **Firestore** stores all competitor intelligence packs, content packs, post records, and vector embeddings used for AI Copilot queries.
* **Firebase Storage** hosts the media files (videos and images) uploaded through the Auto-Post Composer before they are passed to Upload-Post for publishing.

**1. Create a Firebase Project**

Go to the [Firebase console](https://console.firebase.google.com), click **Add project**, and follow the setup wizard. Enable both **Firestore Database** and **Storage** for your project.

**2. Set Your Project ID**

Add your Firebase project ID to `.env`:

```bash .env theme={null}
FIREBASE_PROJECT_ID=your-firebase-project-id
```

The project ID is shown on the Firebase console home page and in your project settings.

**3. Authenticate the Backend**

For local development, authenticate using the Google Cloud CLI:

```bash theme={null}
gcloud auth application-default login
```

Alternatively, download a service account key from **Firebase console → Project Settings → Service accounts → Generate new private key** and point to it:

```bash .env theme={null}
FIREBASE_SERVICE_ACCOUNT_PATH=./serviceAccountKey.json
```

For production deployments (e.g. Vercel), use your hosting provider's secret management to inject the service account credentials directly — no file path needed.

> [!WARNING]
>
> Your Firebase service account key grants admin-level access to your entire Firebase project. Never commit it to version control or expose it in client-side code. Store it as a secret in your hosting provider's secret management system.

***

## Configuration Checklist

Use this checklist to confirm your environment is fully configured before going live:

> [accordion] View full configuration checklist
>
> * [ ] `OPENAI_API_KEY` set and account has access to `gpt-4o-mini`
> * [ ] `EXA_API_KEY` set
> * [ ] `APIFY_TOKEN` set
> * [ ] `UPLOAD_POST_API_KEY` set
> * [ ] `UPLOAD_POST_PROFILE` set to your Upload-Post profile name
> * [ ] At least one social account connected in the Upload-Post dashboard
> * [ ] Firebase project created with Firestore and Storage enabled
> * [ ] `FIREBASE_PROJECT_ID` set
> * [ ] Firebase authentication configured (Application Default Credentials or `FIREBASE_SERVICE_ACCOUNT_PATH`)
> * [ ] `.env` added to `.gitignore`
> * [ ] *(Optional)* `TELEGRAM_BOT_TOKEN` set and webhook registered


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.