> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.messageblue.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.messageblue.ai/_mcp/server.

# Creating your app

Route `/apps and /app-setup`

Find it Where you land after signing in

Who can open it Any signed-in user

An **app** is the container for everything else in MessageBlue: credentials, phone numbers, conversations, the AI agent, webhooks and team members all belong to one app.

## Choosing an app

`/apps` lists what the account owns, with the signed-in email beside the heading. Each row shows the app's name, its industry and its **App ID**. Selecting one opens its [dashboard](/dashboard).

![Your apps screen listing a single app with its industry and app ID, and a sign-out control in the header](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/message-blue.docs.buildwithfern.com/0a4de97f37d53afc3feaaf11f6cec5fc800a15be129397789f8c33c1a4cf7f01/docs/assets/frontend/apps.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260916%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260916T201455Z&X-Amz-Expires=604800&X-Amz-Signature=ea7fb2c07c55acc3783b7b0b8e51ab8616b2973ce9fba742d2023ced3adbdc70&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

This screen has no left rail — it sits outside an app, so the only other control is **sign out** in the top-right corner.

An account supports **one app**. The **Create app** button only appears while you have none; once an app exists it is removed rather than disabled, so there is nothing to press. If you need a second app, use a separate account.

## Creating the app

App setup asks for only two things.

#### App name

Free text, shown wherever the app is identified in the UI. The placeholder suggests the shape: *Example: Blue Concierge API*. Pick something you will recognise — it appears in the dashboard header and the apps list.

#### Industry type

A single choice from: Healthcare, Finance, E-commerce, Education, Real Estate, Hospitality, Logistics, Technology, or Other. It does not restrict any feature.

Pressing **Create app** provisions the app and immediately reveals its credentials.

## Your credentials

Three values appear together in a highlighted panel headed **"Copy this secret now. It is shown only once."**

| Value          | What it is                               | Can you see it again?                                       |
| -------------- | ---------------------------------------- | ----------------------------------------------------------- |
| **Account ID** | Identifies the account that owns the app | Yes — [Settings → API & secrets](/settings#api-and-secrets) |
| **App ID**     | Identifies the app on every API call     | Yes — [Settings → API & secrets](/settings#api-and-secrets) |
| **App Secret** | Signs your API requests                  | **No.** Shown once, at this moment only                     |

The App Secret is never displayed again. Copy it into your secret store before you leave this screen. If you lose it, you are not locked out — you can mint a replacement with **Regenerate secret** in [Settings → API & secrets](/settings#api-and-secrets) — but the old secret stops working the instant you do, and anything still signing with it starts failing.

**Continue to dashboard** takes you to the [dashboard](/dashboard).

## Getting a phone number attached

A freshly created app cannot send or receive anything yet, because no iMessage-capable number belongs to it. The dashboard shows a dismissible **Getting started** card offering three ways forward — *"Three ways to get a working setup — pick whichever fits, you can change later."*

Before the three options, the card asks you to **finish your details**: First name, Last name and Business name. These identify you to the team that provisions numbers and reaches out about billing.

#### Bring your own number

Pair an iMessage-capable Mac you already own. You install the packaged MessageBlue agent on it, sign in, and the Apple ID number on that device starts sending and receiving through MessageBlue.

This is the fastest path if you already have a Mac and a number you want to use, and it is the only path where you keep physical control of the device.

#### Request a number from us

Prefer not to run your own device? Ask for an iMessage-capable number and the MessageBlue team provisions one for this app.

Requests are made from the **Phone numbers** card on the [dashboard](/dashboard#phone-numbers): you say how many numbers you need and optionally add a note. Typical turnaround is **3–5 business days**, and the team confirms before anything is assigned.

#### Test the API first

The same Mac agent setup doubles as a sandbox. Point the API at it and exercise send, receive and webhooks before you put real traffic through.

The **View API credentials** shortcut jumps straight to [Settings → API & secrets](/settings#api-and-secrets).

Once you have completed setup, the card can be dismissed with the **✕** in its corner. Dismissing it is permanent for that app; the same information lives on in the [dashboard](/dashboard) cards and this documentation.