# Connect a service

**Connections** is where you connect the services your projects run on: Stripe, GitHub, Google Cloud, AWS, Vercel, OpenAI and the rest. Each one is tested before anything is saved, and every key is stored encrypted.

For what each service reads before you sign in, see [The public integrations directory](#the-public-integrations-directory).

Only the owner and admins can open Connections. Editors and viewers get **Page not found** there; on their Portfolio and project pages they can ask an admin instead (see [Projects](projects.md)).

## Open Connections

In the sidebar, choose **Connections** (on a phone, **More → Connections**), or press `g` then `c`. The command palette's (`⌘K` / `Ctrl K`) **Connect…** opens **All services** with its search ready, without the first-visit question below.

The page says **Connections**, with a line under it: "Nothing connected yet", or "3 services connected", followed by links when there's something to do ("1 needs you", "4 new resources to review", **Waiting for access · Google Cloud**).

Under it, a row lists what ShipVitals can see: five pillars, **Revenue**, **Costs**, **Health**, **Usage** and **Obligations**, each with **Covered**, **Partial** or **Not connected** (Obligations says "3 tracked" or **None tracked**). Each pillar is a link: one that isn't covered opens the service that would cover it; a covered one shows the connections that feed it.

## The first visit: What do you want to see first?

The first time anyone opens Connections in a workspace, the page asks **What do you want to see first?** ("Connect one service to see your first numbers. Most people start with revenue.").

1. Choose one of the four cards (or press `1`–`4`):
   - **Revenue**: Stripe. The button says **Continue to Stripe**.
   - **Costs**: Google Cloud and Firebase. The button says **Set up Google Cloud** (see [Connect Google Cloud](connect-google-cloud.md)).
   - **Code health**: GitHub. The button says **Continue to GitHub**.
   - **A website**: uptime, TLS and domain expiry. The button says **Watch a website**.
2. Press the gold button (or `Enter` on the card). The service's setup opens.

If you signed in with GitHub, **Code health** comes first. Press **Look around first** to skip the question: you land on the Portfolio, whose gold card carries the first suggestion.

The question is asked once per workspace. After that, Connections shows three tabs: **Suggested**, **Connected** and **All services** (on a phone, a switch at the top).

## Suggested and the setup queue

**Suggested** lists what to connect next, each with a reason:

- **Resume**: a setup you started ("Continue Google Cloud · step 2 of 3").
- **Needs you**: a connection that stopped working.
- **Review**: new resources to bind to projects (see [Review bindings](review-bindings.md)).
- **Detected in your repos**, **Fills a gap** and **Quick win**: the rest of the queue.

Resume, Needs you and Review stay at the top. The rest is your setup queue:

- Press a card's name (or `Enter` on it) to open it. `↑` `↓` move between cards.
- Press **Not now** (or `n` on the card) to hide it. The toast says "… is hidden for 30 days. It stays in All services." with **Undo** for 10 seconds; **Undo** says "… is back in Suggested."
- Drag a card to reorder the queue, or use its menu's **Move up** and **Move down** (or `⌥↑` / `⌥↓`).

When nothing is left: "Nothing to suggest right now. Find more in All services."

## All services

**All services** lists every service under its pillar (**Revenue**, **Costs**, **Health**, **Usage**), each with what it's for, how long it takes, and **Read-only** or "Not read-only at … · ShipVitals only calls …" (the service has no read-only key; the line says what ShipVitals reads with it, such as OpenAI's "usage and cost"). A service that feeds several pillars is listed once, under its first: Vercel, for example, is under **Costs**.

1. Type in **Find a service** (or press `/` anywhere on the page to jump there). The search matches names and what each service is for, and filters the **Not yet** list too.
2. Press the service's name.

After the services, **Entered by hand, or sent by you** holds **Obligations**, **Import a CSV**, **Test results from CI**, **Push metrics** (see [CI and push metrics](ci-and-push-metrics.md)) and **Invoices by email** ("Bills you forward, as cost lines.", see [Invoice inbox](invoice-inbox.md)).

When your plan is close to its limit, the search says so: "4 of 5 connections on Free".

### Not yet

Last on the tab, **Not yet** lists the services ShipVitals doesn't connect yet: "ShipVitals doesn't connect these yet. Here's how their data gets in today, and you can ask to hear when one is ready."

Each entry shows its name with a **Not yet** tag, what it would read, and the way in today, with a link:

| Way in | The entry says | The link | Services |
|---|---|---|---|
| Invoices | "Today: forward …'s invoices." | **Invoices by email** (see [Invoice inbox](invoice-inbox.md)) | Fly.io, Render, Railway, Hetzner, Loops |
| A CSV | "Today: import …'s export as a CSV." | **Import its export** | Azure, GitHub Sponsors |
| Push metrics | "Today: send …'s figures as push metrics." | **Set up push metrics** | Mixpanel, Chrome Web Store, Microsoft Store |

To hear when one is ready:

1. Press **Tell me when it's ready** on its entry.
2. The button gives way to "We'll email you once, when it's ready." Once 5 or more workspaces have asked, it adds how many ("14 workspaces asked.").

Interest is per workspace: anyone else in it sees the same answer. When the connector ships, the workspace gets one email.

### Request a service

For a service that isn't listed at all, use **Request a service** at the very end of the tab:

1. Type its name in **Which service?** (at least 2 characters).
2. Add anything useful in **Anything we should know** (optional).
3. Press **Request it**. The form clears and says "Thanks. We'll email you once, if it's built."

If ShipVitals already connects it, the form says "That one connects already: search for it above." If the request doesn't go through: "That didn't go through. Try again."

## Paste a key

If you already have a key, paste it into **Paste a key** at the top of any tab (or press `c` to jump there). ShipVitals recognises the service from the key and opens its dialog with the key in place. The key stays in this browser until you test it.

- A key that can do more than read is refused before anything is sent. For a Stripe secret key: "This is a secret key, which can change your account. Create a restricted key with Read access instead."
- A key nobody recognises: "We don't recognise that key. Find its service in All services." and the search opens. (On the first visit: "We don't recognise that key. Choose “Look around first” to browse every service.")

## Connect with a key

Most services connect with a key pasted into a dialog. The dialog's title is the service's name, with what it reads and how long it takes.

1. Press **Create a key in …**. The service's own page opens in a new tab. Give the key the name the dialog suggests ("Name it …, so you can recognise it later.").
2. Tick what **The access to give** table lists, in the service's words, with why ShipVitals needs each.
3. Copy the key, come back and paste it into **Key**. Fill any other field the dialog asks for (until then it says "Fill in … to test.").
4. Press **Test connection** (or `Enter`). The button says **Testing…**, then the result replaces the form (see [The test result](#the-test-result)).

Stuck? Open **Where to find this** for the service's own steps, which you can forward to whoever has the keys. **What we store** says how the key is kept: "Encrypted with your workspace key in Google Cloud KMS. Only the sync worker decrypts it, and every use is logged. Delete it here or revoke it in … any time."

If you paste a key from another service, the dialog says "This looks like a key for …." with **Switch to …**.

### A key file: App Store Connect

App Store Connect needs its `.p8` key file as well as identifiers.

1. Drop the file on **Choose the .p8 file**, or press it and choose the file. The dialog says "… is ready. It stays in this browser until you test it." (**Choose another file** replaces it.)
2. If the file is named `AuthKey_` followed by the key id, **Key ID** fills itself. Fill **Issuer ID** and **Vendor number**.
3. To read Apple's monthly proceeds per app as well, tick **Read monthly proceeds**. The key then needs the Finance role too.
4. Press **Test connection**.

The identifiers are kept for 14 days, so you can finish on another device; the file never is.

### Address first: Umami

Umami asks for its address before anything else, self-hosted or Umami Cloud.

1. Type the full address in **Umami address** and press **Continue**: your own Umami's address, or `https://cloud.umami.is` for Umami Cloud. An address that isn't reachable from the internet is caught here ("ShipVitals can't reach … from the internet. …").
2. The dialog shows the address ("… · next, the view-only user"; **Change the address** goes back).
   - Self-hosted: fill **User name** and **Password or API key** with a user that has Umami's View only role.
   - Umami Cloud: leave **User name** empty and paste an API key from Umami's Settings → API keys into **Password or API key**. Umami Cloud has no read-only key, so **All services** lists Umami as "Not read-only at Umami · ShipVitals only calls website stats". It says so even when you connect a self-hosted Umami with a View only user.
3. Press **Test connection**.

### Sign in at the service: Stripe, GitHub, Google

Some services connect by approving ShipVitals at the service instead of pasting a key.

1. The dialog says what the service will ask and what ShipVitals reads (for GitHub: "GitHub will ask which repositories ShipVitals can read. We read code metadata, Actions runs, releases, stars and traffic. We never write to your repositories."; for a service without its own line: "… will ask you to approve read-only access for ShipVitals, then send you back here.") and lists **What ShipVitals reads**.
2. Press **Continue to …** (for example **Continue to Stripe**). The whole page goes to the service.
3. Approve there. You come back to the same dialog, which shows the result: **Connected**, already saved.

Stripe also takes a key: press **Use a key instead** for the key form, and **Continue to Stripe instead** to go back. GitHub connects only this way.

If you cancel at the service, the dialog says "… didn't grant access, so nothing was connected. You can try again or choose another way."

### Nothing to authorise: track a package

npm, PyPI, crates.io, Docker Hub and Homebrew read public download figures, so there's no key and they don't count towards your plan's connections. Each opens a page instead of a dialog.

1. Press the registry's name in **All services** (under **Usage**). The page says **Track a package on …** ("Its daily figures from …. Nothing to authorise."); for npm, **Track an npm package**.
2. Type the name in the registry's field:

   | Registry | Field | Example |
   |---|---|---|
   | npm | **Package** | `lodash` or `@scope/name` |
   | PyPI | **Package** | `requests` |
   | crates.io | **Crate** | `serde` |
   | Docker Hub | **Repository** (a public image) | `nginx` or `yourname/app` |
   | Homebrew | **Formula or cask** | `wget`, or `cask/firefox` for a cask |

3. Choose a **Project**, or leave it empty to start a new project for it ("Leave it empty to start a new project for it.").
4. Press **Track the package**. The page says **Tracking …** with the registry's figure for it now ("… downloads in the last 30 days." for PyPI and crates.io, "… installs in the last 30 days." for Homebrew, "… pulls so far." for Docker Hub), then "Added to …; its daily figures come in with the first sync." (npm says "Latest version …. Added to …; its downloads come in with the first sync.", or "Added to …. Its downloads come in with the first sync." when the latest version isn't known)
5. Press **Track another package**, or **Done**.

If the registry doesn't know the name: "… doesn't know …." (npm: "npm doesn't know a package called …."). A name in the wrong shape: "Enter a name as it is on …." (npm: "Enter an npm package name, like lodash or @scope/name.").

### Google Play: a reports bucket

Google Play earnings and installs come from the reports Play Console writes to Cloud Storage. ShipVitals reads them as your workspace's own Google address, so there's no key to paste.

1. In the dialog, press **Copy the address** under **Your workspace's Google address**.
2. In Play Console, open **Users and permissions → Invite new users**, paste the address and tick only **View app information and download bulk reports** and **View financial data**. Invite it. Google can take up to a day before the address can read the reports.
3. In Play Console, open **Download reports → Financial** and choose **Copy Cloud Storage URI**. Paste it into **Cloud Storage URI**.
4. Press **Test connection**.

When an app also sells through RevenueCat or reports through App Store Connect, the same sale is counted once.

## The test result

The result shows who ShipVitals found ("… account" with a **live** or **test** tag), the checks one by one, **Access** (what's needed, granted, missing, or more than needed), and what was found ("214 resources found · …").

Nothing is saved until you say so.

| The result says | What it means | What to do |
|---|---|---|
| **Test passed** | It works. "Nothing is saved until you choose Done or Next." | Press **Done** to save it and go to the **Connected** tab, or **Next: …** to save it and open the next service in your queue (`Enter`; `⌘Enter` / `Ctrl+Enter` is **Done**). |
| **Works, with warnings** | It works, but something is missing, listed in the checks. "Not saved yet. Save with warnings to connect it." | Press **Save with warnings**, or **Fix and test again** to change the key. |
| **Not connected** | It didn't work. The line says what happened and what to do (see the table below). | Fix it and press **Test again**, or **Change the key**. |

**Next: …** shows how many more are waiting ("3 more suggested: …"). When a connection found new resources, **Review bindings** takes you to them.

To add a second account of the same service (another Stripe account, say), press **Connect another … account** on a result that names its account. A passed test is saved first; then the same dialog opens again, empty.

Wrong account? Press **Not this account? Try another key** on a passed result: nothing was saved. After installing the Stripe App or the GitHub App, which saves at once, it's **Not this account? Disconnect and try another key**, next to **Connect another … account**. A Google sign-in makes one connection for Google Analytics and one for Search Console, so its result offers **Not this account? Disconnect both and sign in again**: both connections go, ShipVitals' access at Google ends once the last of them is gone, and the dialog offers **Continue to Google** again. It offers no **Connect another … account**: to add another Google account, sign in again with it. To keep one of the two, disconnect the other from **Connected** instead (see [Connection health](connection-health.md#disconnect)).

When the service itself was down or unreachable, **Not connected** also offers **Save and retry later**. The result says **Saved, not tested yet**: "ShipVitals tests it again at …, and it starts syncing once … answers."

Every failure has **Details** (the service's code, the kind of error and a request id) and **Get help**, which opens an email to support with those filled in. Never paste your key into it.

## Already connected

If the account behind the key is already connected, saving says **Already connected**: "Already connected: …, added by … on …." and "Replacing its key keeps all its history."

- Press **Replace its key** to swap the stored key for the new one.
- Press **Cancel** to go back to the form.

Most services check which account a key belongs to, such as Anthropic, ElevenLabs, Neon and Umami Cloud. Where a service doesn't say whose a key is (OpenRouter, MailerSend, Mailgun, Postmark, Resend, SendGrid, Plausible, Fathom, and OpenAI when the key names no organisation), ShipVitals can't tell a new key for the same account from another account's, so a replacement key is accepted. Otherwise, when you replace a key (from **Replace key** or **Reconnect …** on [a connection that needs you](connection-health.md)) with a key for a different account, the key is refused and the result says "This key is for another account than the connection it would replace. Add it as a new connection instead." Press **Add it as a new connection**, or **Change the key**.

## Limits

- Testing keys: about 20 tests an hour per person and per workspace. Past that the result says **Not tested**: "You've tested many keys in the last hour. Try again at …." and "Keys already saved keep syncing." Press **Back to Connections**.
- Your plan's connections: a connection over your plan's limit is still tested and saved, but says **Saved, but paused**: "Saved, but paused: … includes … connections. It starts syncing when you remove one or change plan." It shows as Paused on **Connected**, with **See plans**.

## When it doesn't work

The line under **Not connected** names the service in place of "…".

| Kind of error | The result says | What to do |
|---|---|---|
| auth | "… didn't accept this credential. Check that you copied all of it, or create a new one." | Copy the whole key again, or create a new one. |
| scope | "… let ShipVitals in, but not to everything it needs. Add the missing access listed below and test again." | Add what **Access** lists as **Missing** to the key at the service, then **Test again**. |
| revoked | "ShipVitals' access to … was removed. Your data up to then is kept; connect again to resume." | Create a new key or sign in again. |
| rate_limit | "… is limiting requests right now. Your credential looks fine; ShipVitals will finish when the limit resets." | Wait, then **Test again**. |
| quota | "… says the account is out of quota or credit. Top it up or raise the limit, then test again." | Top up the account at the service. |
| not_found | "ShipVitals reached …, but couldn't find what it was asked to read. Check the name or id you entered." | Check the other fields against **Where to find this**. |
| provider_down | "… didn't respond properly. This is on their side: save now and ShipVitals will test again later." | Press **Save and retry later**. |
| network | "ShipVitals couldn't reach … just now. This is usually brief: test again in a minute." | Wait a minute, then **Test again**, or **Save and retry later**. |
| schema | "… answered in a shape ShipVitals doesn't recognise, perhaps after a change on their side. Your data up to now is kept; test again later, and tell us if it lasts." | Test again later; press **Get help** if it lasts. |
| config | "This connection's settings aren't right for …. Check what you entered against the steps above." | Check the fields against **Where to find this**. |

Two services say more:

- **Anthropic**, config: "Anthropic's cost reports need an organisation Admin API key (sk-ant-admin…). Individual accounts don't have one: add Anthropic invoices by hand or import a CSV instead."
- **Umami (self-hosted)**, network: "ShipVitals can't reach your Umami instance. It needs to be reachable from the internet: check the address, including any base path."

Other things the dialog can say:

| The dialog says | What to do |
|---|---|
| "Check …: ShipVitals can't use what's there." | The field named is in the wrong shape. Fix it and press **Test connection**. |
| "… didn't grant access, so nothing was connected. You can try again or choose another way." | You cancelled at the service. Press **Continue to …** again, or **Use a key instead**. |
| "This … sign-in took too long, so nothing was connected. Start again." | Press **Continue to …** again. |
| "An owner of the organisation has to approve the install in …. It connects once they do." | Ask an owner of the GitHub organisation to approve the ShipVitals app. |
| "This … installation is connected to another ShipVitals workspace." | Disconnect it in the other workspace first. |
| "Connecting … isn't available on ShipVitals yet. It opens for every workspace at once, and this dialog will offer it then." | Use a key instead, where the dialog offers one. Nothing in your workspace changes this. |
| "That didn't go through. Check your connection and try again." | Check your internet connection and try again. |

## The services, family by family

Services new in the beta are marked **Beta** on their public pages (see [The public integrations directory](#the-public-integrations-directory)): they work, and are still being checked against more accounts. The app marks them the same way: a **Beta** label in **All services**, and a line saying so in the connection dialog.

Each key below is created at the service: press **Create a key in …** in the dialog, follow **Where to find this**, and tick what **The access to give** lists. Fields marked optional can stay empty for most accounts.

### Package registries: no key

**PyPI**, **crates.io**, **Docker Hub** and **Homebrew**, like npm, need only a package name: see [Nothing to authorise: track a package](#nothing-to-authorise-track-a-package).

### Web analytics

| Service | What you paste | Optional fields |
|---|---|---|
| **Plausible** | A Stats API key (Settings → API Keys → New API Key → Stats API) | **Plausible address**, for a self-hosted Plausible |
| **Fathom** | An API key with Read only access to all sites (Settings → API) | |
| **PostHog** | A personal API key (it starts with `phx_`) with read access to User, Project and Query | **PostHog address** (`https://eu.posthog.com` for EU Cloud, or your own), **Project ID** |
| **Umami** (self-hosted or Umami Cloud) | See [Address first: Umami](#address-first-umami) | |

Each site or project becomes a resource, matched to a project by its domain (see [Review bindings](review-bindings.md)).

### Merchants of record

**Paddle**, **Lemon Squeezy**, **Polar** and **Gumroad** feed revenue, MRR and the P&L, with the merchant's fee and the tax it collected kept apart, so net revenue is right.

| Service | What you paste | Read-only? |
|---|---|---|
| **Paddle** | An API key (Developer tools → Authentication) with only `transaction.read`, `subscription.read`, `adjustment.read` and `product.read`; it starts with `pdl_live_apikey_` | Read-only |
| **Lemon Squeezy** | An API key (Settings → API, with Test mode off) | Not read-only: Lemon Squeezy has no read-only keys |
| **Polar** | An organization access token (Settings → Developers → New Token) with only the read scopes listed; it starts with `polar_oat_` | Read-only |
| **Gumroad** | An access token from an application you create in Settings → Advanced (**Generate access token**) | Not read-only: Gumroad's tokens can't be limited to reading |

### In-app revenue

| Service | What you give it |
|---|---|
| **RevenueCat** | A V2 secret API key (it starts with `sk_`) with read-only access to the permissions listed. **Project ID** only if the key reads more than one project. |
| **App Store Connect** | Tick **Read monthly proceeds** in its dialog (see [A key file: App Store Connect](#a-key-file-app-store-connect)). |
| **Google Play** | Your workspace's Google address invited in Play Console, and the reports' **Cloud Storage URI** (see [Google Play: a reports bucket](#google-play-a-reports-bucket)). |

A sale seen by more than one of them on the same project is counted once.

### Hosting and platforms

| Service | What you paste | Optional fields | Read-only? |
|---|---|---|---|
| **Vercel** | An access token scoped to the team that owns your projects (Account Settings → Tokens) | **Team ID**, only for a token that reaches several teams | Not read-only: Vercel's tokens can't be limited to reading |
| **Cloudflare** | An API token. **Create a key in Cloudflare** opens the Create API Token page with ShipVitals' read permissions already chosen; add Registrar domains read if you buy domains there | **Account ID**, only for a token that reaches several accounts | Read-only |
| **Supabase** | A scoped access token (Account → Access Tokens) with read access to organizations, projects, analytics usage and add-ons | **Organization slug**, only for a token that reaches several organizations | Read-only |
| **Netlify** | A personal access token (User settings → Applications) | **Team slug**, only for a token that reaches several teams | Not read-only: Netlify's tokens can't be limited to reading |
| **DigitalOcean** | A personal access token with Custom Scopes: read for account, billing, droplet, app and domain (or Read Only) | | Read-only |

Vercel reads usage cost, production deploys, domains and Web Analytics. Cloudflare reads zones, Web Analytics and Registrar renewals. DigitalOcean's invoice items are real costs. Supabase's plan and compute, Netlify's plan and Cloudflare's Workers, R2 and plan costs are estimates: on the Costs tab their source says "Estimated: plan price × usage" until the invoice replaces them (see [Costs and budgets](costs-and-budgets.md) and [Invoice inbox](invoice-inbox.md)).

Fly.io, Render, Railway, Hetzner and Azure are **Not yet**: forward their invoices (Azure: import its cost export as a CSV).

### Mail

| Service | What you paste | Optional fields | Read-only? |
|---|---|---|---|
| **Resend** | An API key with Full access (it starts with `re_`): Resend's sending-access keys can't read stats | **Plan price per month** | Not read-only |
| **Postmark** | An account token (every server) or a server token (that one server), from the API Tokens tab | **On the free Developer plan** (tick it to see the 100 emails a month cap), **Plan price per month** | Not read-only |
| **SendGrid** | An API key with Restricted Access: Read Access to Stats, Sender Authentication and User Account (it starts with `SG.`) | **Region** (EU only for a subuser in SendGrid's EU region), **Plan price per month** | Read-only |

**Plan price per month** is used to estimate cost per project, since none of the three has a billing API. Amazon SES arrives as a service line of [AWS](#connect-aws). Loops is **Not yet**: forward its invoices.

### CI beyond GitHub

GitLab, CircleCI and Bitbucket Pipelines aren't connections: their test results arrive through **Test results from CI** in **All services**, under **Where your tests run** (see [CI and push metrics](ci-and-push-metrics.md)). On GitLab.com no secret is needed once you **Bind the GitLab project**; CircleCI and Bitbucket upload with a token stored as `SHIPVITALS_TOKEN`.

## Connect AWS

AWS costs come from Cost Explorer, read through a read-only role you create in your AWS account with CloudFormation. No access key is asked for or stored. It takes about 3 minutes.

### Open the setup

In **All services**, press **AWS** under **Costs**. The page says **Connect AWS** ("Daily costs per account and service · …") with three numbered steps: **Your account**, **Create the role** and **Check access** ("Step 1 of 3"). **Back to Connections** leaves it.

Your place is saved on every step: the header then says **Saved · continues on any device**, and **Suggested** offers to resume it.

### Step 1: Your account

The step asks **Which AWS account?**

1. Type the 12 digits in **AWS account ID** ("12 digits, from the account menu at the top right of the AWS console. Use your management account to see every linked account's costs."), without dashes.
2. Press **Continue**.

The step also says "No access key is asked for. ShipVitals reads through a read-only role you create, and you can delete it any time." A wrong ID says "Enter the 12-digit account ID, without dashes."

### Step 2: Create the role

The step shows what the role is before you create it: "Create a role in … that only ShipVitals can assume, and only with your workspace's External ID. Read what it allows first:"

1. Check the values shown:
   - **External ID**, with **Copy the External ID**: your workspace's own, so no one else can use the role.
   - **ShipVitals principal**, with **Copy the ShipVitals principal**: the AWS identity allowed to assume the role.
   - **Role name**: `ShipVitalsReadOnly-…`, named for this workspace.
   - "It can only read:" `ce:GetCostAndUsage` and `ce:GetDimensionValues`.
2. Read the **CloudFormation template** shown below them.
3. Press **Open in AWS CloudFormation**. AWS's **Quick create stack** page opens in a new tab with your values filled in.
4. At AWS, tick "I acknowledge that AWS CloudFormation might create IAM resources with custom names", then choose **Create stack**.
5. Come back and press **Continue to Check access** ("CloudFormation takes about a minute. Check access waits for the role.").

If the link isn't available on this server, the step says "The template link isn't published on this server yet. In the CloudFormation console, create a stack from the template above and set ExternalId, ShipVitalsPrincipal and RoleName to the values shown."

To remove ShipVitals' access later, delete the stack named on the step ("To remove ShipVitals' access later, delete the stack ….").

### Step 3: Check access

The check starts by itself: "ShipVitals waits for the role to exist, then reads the last 30 days of costs as it. AWS charges your account $0.01 for each Cost Explorer request: this check makes 1, the first sync about 13, then about 2 a day."

1. While the stack is being created, the step says "Waiting for the role …" ("Once the stack shows CREATE_COMPLETE, this continues by itself. Still waiting? Check the account ID and that the stack's ExternalId matches.").
2. Once the role exists, it says **Checking access** and lists the **Checks** one by one.
3. The result:
   - "AWS is connected. The first sync reads the last 12 months of costs." Press **Done** to go to **Connected**.
   - "AWS is connected, with a warning below. Costs appear once Cost Explorer has them." It's saved; press **Done**.
   - "ShipVitals couldn't read costs as the role." The checks say what failed. Fix it and press **Check again**.

| The step says | What to do |
|---|---|
| "The role didn't appear in 10 minutes. Check the stack in CloudFormation, then check again." | Open the stack at AWS. If it failed, create it again from step 2. Then **Check again**. |
| "This AWS account is already connected to this workspace." | Nothing to do: it's on **Connected**. |
| "Saved, but paused: your plan has no room for another connection. …" | Remove a connection or change plan. |
| "You've run many checks in the last hour. Try again later." | Wait, then **Check again**. |
| "The check didn't finish. Try again in a minute." | Wait a minute, then **Check again**. |

Leaving the step stops the wait; coming back to it starts it again. Costs sync once a day, by service and linked account, and Amazon SES shows as one of the service lines.

## The public integrations directory

Anyone can see what ShipVitals connects without an account, on the public site.

1. Open `/integrations` (the site's footer: **Integrations**). The page says **Integrations**: "… services connect today. … more are listed as Not yet, each with another way in." and "Don't see yours? Import a CSV, forward invoices, or ask for it."
2. Type in **Search services** to filter. Services are grouped by **Revenue**, **Costs**, **Usage**, **Health** and **Obligations**, each row with how it connects ("Read-only key · about 2 minutes", "Nothing to authorise", "Guided setup", …) and a state: **Available**, **Beta** or **Not yet**.
3. Press a service. Its page, **Connect … to ShipVitals**, has **What it reads** (each scope and why), **How to connect** (the steps, with links), **How to revoke**, **What it powers**, **Sync** and **Docs**. A Beta service says "Beta: this connector is new in the beta, and we're still checking it against more accounts."
4. Press **Connect …**. You sign in (or sign up) and land on that service's setup in your workspace.

A **Not yet** page (**… isn't connected yet**) has what it would read, **The way in today**, and **Tell me when it's ready**: sign in, and the workspace's interest is recorded on arrival: owners and admins land in **All services**, and editors and viewers on a page that says "We'll email you once, when it's ready." **Request a service** at the end of the index takes you to the same form in the app.

### A service's page

Every service has a page in the integrations directory at `/integrations/<id>` (for example `/integrations/stripe`): what ShipVitals reads, how to connect and revoke it, what it powers, how often it syncs, and **Troubleshooting**, each error a connection can hit and its fix. Google Cloud also has a guide of its own, [Connect Google Cloud](connect-google-cloud.md).

## Keyboard

| Key | Does |
|---|---|
| `g` then `c` | Go to Connections |
| `c` | Put the cursor in **Paste a key** |
| `/` | Search **All services** |
| `↑` `↓`, `Enter` | Move between cards, open one |
| `n` | **Not now** on the focused card |
| `1`–`4` | Choose on the first visit (`Enter` on a card opens it) |
| `Enter` | In the dialog, **Test connection**; on a result, its primary button |
| `⌘Enter` / `Ctrl+Enter` | **Done** when **Next: …** is the primary button |
| `Esc` | Close the dialog |

Press `?` for **Keyboard shortcuts**: it lists these, the review's and the health centre's keys under each screen's name.

Single-key shortcuts follow **Single-key shortcuts** in [Account settings](account-settings.md).
