Connecting customers
How a customer creates an integration key for your platform, how to receive and store it, and what to do when they revoke it or close their organization.
Every customer connects your platform themselves, from the Vitruve app. You never ask for their password and never sign in to their organization.
How a customer creates a key
The Owner of an organization whose plan includes export integrations, currently Elite or Professional, or a trial, opens Settings → Integrations → Export in the Vitruve app, selects Create next to your platform's name, and copies the key. The steps they follow are in Connect wearables and external services: link to it from your own connection instructions.
- There is one key per platform per organization. A customer with several Vitruve organizations creates one key in each.
- A key opens one organization and only for your platform: it does not work with another partner's secret, and it does not work on its own.
- Coaches cannot create keys. If your user is a coach, they need their organization's owner to do it.
Receive and store the key
Give customers a field in your platform's settings to paste the key into. When they save it:
- Call
GET /organizationwith the key and your secret. A200proves the key works and tells you which organization it opens: store itsidnext to your customer account. - Store the key encrypted at rest, linked to that customer. It is the only credential you hold for them.
- If the same Vitruve organization is already linked to another of your accounts, decide whether to replace or refuse: Vitruve does not prevent it.
When the connection ends
| What happened | What you see | What to do |
|---|---|---|
| The customer revoked the key (Delete in Settings) | 401 Invalid API key | Mark the customer disconnected and ask them to reconnect. Do not retry: repeated 401s use up your secret's failed-authentication budget, and past it every customer answers 429 until the minute ends. |
| The organization was closed | 401 Organization is not active | Stop syncing and delete the key. |
| The plan stopped including integrations, or the subscription ended | 403 Your plan no longer includes API access | The key is still valid. See Plans and history. |
There is no webhook for any of these. Handle the answers wherever you call the API.
When a customer disconnects your platform on your side, delete their key too, and tell them they can also delete it in Settings → Integrations → Export.
Partner authentication
Every partner request sends the customer's integration key and your partner secret, from a registered IP address. The checks, their errors, and rotation.
Plans and history
What a customer's plan allows your integration to read, how much history a key reads, and how to react when the plan changes.