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

# Connections

> Run email, payments, auth, database and deploy capabilities on your own accounts, and connect social accounts through Pramaan.

Some capabilities act on accounts you own: they send your email, charge your customers or read
your database. These run on an account you connect, and Pramaan does not charge for them.

A capability's reference page says **Runs on your own connected account: free** when it needs a
connection.

Social and texting work differently: they run on Pramaan's accounts, need no credentials from
you and are charged per call. See [social accounts](#social-accounts) below and
[numbers and US registration](https://docs.pramaan.dev/guides/numbers.md).

## Connect an account

1. Open **Connections** in the dashboard. Accounts are grouped by slot: `email`, `payments`,
   `auth`, `db` and `deploy`.
2. Pick the service you use and paste the fields it asks for (usually an API key; sometimes a
   project URL).
3. Pramaan checks the credentials with one read-only call before saving them.

Credentials are encrypted at rest and only decrypted for the call that needs them. After saving,
the dashboard shows the last four characters only.

## When nothing is connected

Calling a capability whose slot has no connected account returns `409 connection_required`. The
error tells you which slot to connect:

```json theme={null}
{
  "error": {
    "code": "connection_required",
    "message": "An account connection is missing. Connect it with apps.connection.start, then retry.",
    "request_id": "req_01J...",
    "retryable": false,
    "slot": "email"
  }
}
```

## Rotate or remove

Replace the credentials from the same page to rotate them. Removing a connection stops calls on
it right away; the next call returns `connection_required`.

## Social accounts

You don't paste anything for social. The person who owns the account (you, or one of your users)
signs in on the platform and approves access:

1. Call `social.account.connect.start` with the `platform` and a `returnUrl` on your site. You
   get a `connectUrl` and a `ref`.
2. Send the person to `connectUrl`. They sign in, pick the page or profile if the platform asks,
   and approve.
3. They land back on your `returnUrl` with `status=connected`, `failed` or `pending` in the query
   string, plus `platform`, and `accountId` when connected. When it failed, `error` says why
   (`denied`, `wrong_account`, `nothing_to_connect`, `missing_permissions`, `unavailable` or
   `failed`) and `retry=true` means trying again can fix it.
4. Don't trust the query string alone: confirm with `social.account.connect.status` (pass the
   `ref`), or wait for the `connection.updated` event.

The sign-in link returns people to your `returnUrl` for 15 minutes after you start the flow. If
someone takes longer, they are not sent back to your site: check `social.account.connect.status`
(the account may still have connected) or start again.

The account then appears in `social.accounts.list`; use its `accountId` to post, read the inbox
and so on. `social.account.disconnect` removes it.

```ts theme={null}
const { connectUrl, ref } = await pramaan.run("social.account.connect.start", {
  platform: "instagram",
  returnUrl: "https://app.example.com/social/connected",
});
// ...later, on your return page
const { status, accounts } = await pramaan.run("social.account.connect.status", { ref });
```

Your accounts are yours alone: every call only ever sees and acts on the accounts you connected.

Sending is limited to 200 posts and messages a day per account by default. Past that, calls
return `429 rate_limited` until the next day (UTC).

## Receive events

Pramaan passes events on to your webhook endpoints as plain events: `payment.completed`,
`social.post.published`, `social.message.received`, `connection.updated`,
`sms.message.delivered` and more. See [webhooks](https://docs.pramaan.dev/guides/webhooks.md).

* **Social and texting:** nothing to set up. Events for your accounts and numbers arrive by
  themselves.
* **Payments:** events identify your connected account themselves. Open the account's card on
  the **Connections** page if the service asks for a webhook URL.


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