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.
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).
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.").
- 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).
- Code health: GitHub. The button says Continue to GitHub.
- A website: uptime, TLS and domain expiry. The button says Watch a website.
- Press the gold button (or
Enteron 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).
- 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
Enteron it) to open it.↑↓move between cards. - Press Not now (or
non 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.
- 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. - 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) and Invoices by email ("Bills you forward, as cost lines.", see Invoice inbox).
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
- Invoices
- The entry says
- "Today: forward …'s invoices."
- The link
- Invoices by email (see Invoice inbox)
- Services
- Fly.io, Render, Railway, Hetzner, Loops
- Way in
- A CSV
- The entry says
- "Today: import …'s export as a CSV."
- The link
- Import its export
- Services
- Azure, GitHub Sponsors
- Way in
- Push metrics
- The entry says
- "Today: send …'s figures as push metrics."
- The link
- Set up push metrics
- Services
- Mixpanel, Chrome Web Store, Microsoft Store
| Way in | The entry says | The link | Services |
|---|---|---|---|
| Invoices | "Today: forward …'s invoices." | Invoices by email (see Invoice inbox) | 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:
- Press Tell me when it's ready on its entry.
- 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:
- Type its name in Which service? (at least 2 characters).
- Add anything useful in Anything we should know (optional).
- 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.
- 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.").
- Tick what The access to give table lists, in the service's words, with why ShipVitals needs each.
- 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.").
- Press Test connection (or
Enter). The button says Testing…, then the result replaces the form (see 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.
- 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.)
- If the file is named
AuthKey_followed by the key id, Key ID fills itself. Fill Issuer ID and Vendor number. - To read Apple's monthly proceeds per app as well, tick Read monthly proceeds. The key then needs the Finance role too.
- 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.
- Type the full address in Umami address and press Continue: your own Umami's address, or
https://cloud.umami.isfor Umami Cloud. An address that isn't reachable from the internet is caught here ("ShipVitals can't reach … from the internet. …"). - 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.
- 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.
- 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.
- Press Continue to … (for example Continue to Stripe). The whole page goes to the service.
- 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.
- 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.
- Type the name in the registry's field:
- Registry
- npm
- Field
- Package
- Example
lodashor@scope/name
- Registry
- PyPI
- Field
- Package
- Example
requests
- Registry
- crates.io
- Field
- Crate
- Example
serde
- Registry
- Docker Hub
- Field
- Repository (a public image)
- Example
nginxoryourname/app
- Registry
- Homebrew
- Field
- Formula or cask
- Example
wget, orcask/firefoxfor a cask
| 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 |
- Choose a Project, or leave it empty to start a new project for it ("Leave it empty to start a new project for it.").
- 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)
- 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.
- In the dialog, press Copy the address under Your workspace's Google address.
- 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.
- In Play Console, open Download reports → Financial and choose Copy Cloud Storage URI. Paste it into Cloud Storage URI.
- 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
- Test passed
- What it means
- It works. "Nothing is saved until you choose Done or Next."
- What to do
- 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+Enteris Done).
- The result says
- Works, with warnings
- What it means
- It works, but something is missing, listed in the checks. "Not saved yet. Save with warnings to connect it."
- What to do
- Press Save with warnings, or Fix and test again to change the key.
- The result says
- Not connected
- What it means
- It didn't work. The line says what happened and what to do (see the table below).
- What to do
- Fix it and press Test again, or Change the key.
| 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).
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) 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
- auth
- The result says
- "… didn't accept this credential. Check that you copied all of it, or create a new one."
- What to do
- Copy the whole key again, or create a new one.
- Kind of error
- scope
- The result says
- "… let ShipVitals in, but not to everything it needs. Add the missing access listed below and test again."
- What to do
- Add what Access lists as Missing to the key at the service, then Test again.
- Kind of error
- revoked
- The result says
- "ShipVitals' access to … was removed. Your data up to then is kept; connect again to resume."
- What to do
- Create a new key or sign in again.
- Kind of error
- rate_limit
- The result says
- "… is limiting requests right now. Your credential looks fine; ShipVitals will finish when the limit resets."
- What to do
- Wait, then Test again.
- Kind of error
- quota
- The result says
- "… says the account is out of quota or credit. Top it up or raise the limit, then test again."
- What to do
- Top up the account at the service.
- Kind of error
- not_found
- The result says
- "ShipVitals reached …, but couldn't find what it was asked to read. Check the name or id you entered."
- What to do
- Check the other fields against Where to find this.
- Kind of error
- provider_down
- The result says
- "… didn't respond properly. This is on their side: save now and ShipVitals will test again later."
- What to do
- Press Save and retry later.
- Kind of error
- network
- The result says
- "ShipVitals couldn't reach … just now. This is usually brief: test again in a minute."
- What to do
- Wait a minute, then Test again, or Save and retry later.
- Kind of error
- schema
- The result says
- "… 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."
- What to do
- Test again later; press Get help if it lasts.
- Kind of error
- config
- The result says
- "This connection's settings aren't right for …. Check what you entered against the steps above."
- What to do
- Check the fields against Where to find this.
| 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
- "Check …: ShipVitals can't use what's there."
- What to do
- The field named is in the wrong shape. Fix it and press Test connection.
- The dialog says
- "… didn't grant access, so nothing was connected. You can try again or choose another way."
- What to do
- You cancelled at the service. Press Continue to … again, or Use a key instead.
- The dialog says
- "This … sign-in took too long, so nothing was connected. Start again."
- What to do
- Press Continue to … again.
- The dialog says
- "An owner of the organisation has to approve the install in …. It connects once they do."
- What to do
- Ask an owner of the GitHub organisation to approve the ShipVitals app.
- The dialog says
- "This … installation is connected to another ShipVitals workspace."
- What to do
- Disconnect it in the other workspace first.
- The dialog says
- "Connecting … isn't available on ShipVitals yet. It opens for every workspace at once, and this dialog will offer it then."
- What to do
- Use a key instead, where the dialog offers one. Nothing in your workspace changes this.
- The dialog says
- "That didn't go through. Check your connection and try again."
- What to do
- Check your internet connection and try again.
| 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): 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.
Web analytics
- Service
- Plausible
- What you paste
- A Stats API key (Settings → API Keys → New API Key → Stats API)
- Optional fields
- Plausible address, for a self-hosted Plausible
- Service
- Fathom
- What you paste
- An API key with Read only access to all sites (Settings → API)
- Optional fields
- Service
- PostHog
- What you paste
- A personal API key (it starts with
phx_) with read access to User, Project and Query - Optional fields
- PostHog address (
https://eu.posthog.comfor EU Cloud, or your own), Project ID
- Service
- Umami (self-hosted or Umami Cloud)
- What you paste
- See Address first: Umami
- Optional fields
| 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 |
Each site or project becomes a resource, matched to a project by its domain (see Review bindings).
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
- Paddle
- What you paste
- An API key (Developer tools → Authentication) with only
transaction.read,subscription.read,adjustment.readandproduct.read; it starts withpdl_live_apikey_ - Read-only?
- Read-only
- Service
- Lemon Squeezy
- What you paste
- An API key (Settings → API, with Test mode off)
- Read-only?
- Not read-only: Lemon Squeezy has no read-only keys
- Service
- Polar
- What you paste
- An organization access token (Settings → Developers → New Token) with only the read scopes listed; it starts with
polar_oat_ - Read-only?
- Read-only
- Service
- Gumroad
- What you paste
- An access token from an application you create in Settings → Advanced (Generate access token)
- Read-only?
- Not read-only: Gumroad's tokens can't be limited to reading
| 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
- RevenueCat
- What you give it
- 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.
- Service
- App Store Connect
- What you give it
- Tick Read monthly proceeds in its dialog (see A key file: App Store Connect).
- Service
- Google Play
- What you give it
- Your workspace's Google address invited in Play Console, and the reports' Cloud Storage URI (see Google Play: a reports bucket).
| 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). |
| Google Play | Your workspace's Google address invited in Play Console, and the reports' Cloud Storage URI (see 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
- Vercel
- What you paste
- An access token scoped to the team that owns your projects (Account Settings → Tokens)
- Optional fields
- Team ID, only for a token that reaches several teams
- Read-only?
- Not read-only: Vercel's tokens can't be limited to reading
- Service
- Cloudflare
- What you paste
- 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
- Optional fields
- Account ID, only for a token that reaches several accounts
- Read-only?
- Read-only
- Service
- Supabase
- What you paste
- A scoped access token (Account → Access Tokens) with read access to organizations, projects, analytics usage and add-ons
- Optional fields
- Organization slug, only for a token that reaches several organizations
- Read-only?
- Read-only
- Service
- Netlify
- What you paste
- A personal access token (User settings → Applications)
- Optional fields
- Team slug, only for a token that reaches several teams
- Read-only?
- Not read-only: Netlify's tokens can't be limited to reading
- Service
- DigitalOcean
- What you paste
- A personal access token with Custom Scopes: read for account, billing, droplet, app and domain (or Read Only)
- Optional fields
- Read-only?
- Read-only
| 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 and Invoice inbox).
Fly.io, Render, Railway, Hetzner and Azure are Not yet: forward their invoices (Azure: import its cost export as a CSV).
- Service
- Resend
- What you paste
- An API key with Full access (it starts with
re_): Resend's sending-access keys can't read stats - Optional fields
- Plan price per month
- Read-only?
- Not read-only
- Service
- Postmark
- What you paste
- An account token (every server) or a server token (that one server), from the API Tokens tab
- Optional fields
- On the free Developer plan (tick it to see the 100 emails a month cap), Plan price per month
- Read-only?
- Not read-only
- Service
- SendGrid
- What you paste
- An API key with Restricted Access: Read Access to Stats, Sender Authentication and User Account (it starts with
SG.) - Optional fields
- Region (EU only for a subuser in SendGrid's EU region), Plan price per month
- Read-only?
- Read-only
| 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. 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). 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?
- 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.
- 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:"
- 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:GetCostAndUsageandce:GetDimensionValues.
- Read the CloudFormation template shown below them.
- Press Open in AWS CloudFormation. AWS's Quick create stack page opens in a new tab with your values filled in.
- At AWS, tick "I acknowledge that AWS CloudFormation might create IAM resources with custom names", then choose Create stack.
- 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."
- 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.").
- Once the role exists, it says Checking access and lists the Checks one by one.
- 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
- "The role didn't appear in 10 minutes. Check the stack in CloudFormation, then check again."
- What to do
- Open the stack at AWS. If it failed, create it again from step 2. Then Check again.
- The step says
- "This AWS account is already connected to this workspace."
- What to do
- Nothing to do: it's on Connected.
- The step says
- "Saved, but paused: your plan has no room for another connection. …"
- What to do
- Remove a connection or change plan.
- The step says
- "You've run many checks in the last hour. Try again later."
- What to do
- Wait, then Check again.
- The step says
- "The check didn't finish. Try again in a minute."
- What to do
- Wait a minute, then 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.
- 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." - 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.
- 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."
- 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.
Keyboard
- Key
gthenc- Does
- Go to Connections
- Key
c- Does
- Put the cursor in Paste a key
- Key
/- Does
- Search All services
- Key
↑↓,Enter- Does
- Move between cards, open one
- Key
n- Does
- Not now on the focused card
- Key
1–4- Does
- Choose on the first visit (
Enteron a card opens it)
- Key
Enter- Does
- In the dialog, Test connection; on a result, its primary button
- Key
⌘Enter/Ctrl+Enter- Does
- Done when Next: … is the primary button
- Key
Esc- Does
- Close the dialog
| 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.