Integrations

Read the configurations an organization saved for your installed app, connect them, and report whether each one works.

Every installed connector uses the integrations API. It is how your app learns what an organization configured for it, and how it says whether that configuration works. Your app reads its configurations here, with their secrets. It then reports each configuration ready or failed.

Hydda One starts to use your app only after it reports a configuration ready. The billing queues and signing sends wait for that report.

How an app is set up

Three things connect your app to an organization.

• The manifest is your app’s description. It names the parts of Hydda One the app fills, such as billing.invoicing or crm.signing. It names the roles the app needs, and the configuration fields at each level. It can also name a setupAddress.
• The installation is your app inside one organization. Only an administrator of the organization installs it, and consents to the roles the manifest requests.
• A configuration holds the values and secrets an administrator saved for your installation. It belongs to one operational context: the organization itself (level organization) or one business (level business_context).

Saving a configuration grants your installation the role that part of Hydda One needs, at that context. A configuration at a level your manifest fills nothing at grants no role. An invoicing connector, for example, keeps each company’s ERP credentials in a configuration at that business.

What the token needs

The caller is the installation itself, with its own token. See Authentication. No role is needed.

Two kinds of token are accepted:

• An installed connector’s token from the installation-token grant.
• The token of an organization’s own Application that the organization installed as an app.

The installation must be active. A disabled installation, or a token that matches no installation, answers 403. A request without a token answers 401.

The flow

An app with a setupAddress connects each configuration on its own page. Use this when you need an OAuth consent, or when you collect secrets yourself.

Each call is described in the integrations reference.

1. Receive the administrator. The browser arrives at your setupAddress with three query parameters: reference, installation_id and return_url.
2. Get a token for the installation. Use installation_id to request a token for that installation. Do not trust the id alone. The redeem in the next step proves it, because a token for another installation redeems nothing.
3. Redeem the reference. Call POST /v1/integrations/connection-references/redeem with reference. The answer names the configurationId the administrator is connecting, its operationalContextId and its level.
4. Read the configuration. Call GET /v1/integrations/configurations and find the configuration by its id.
5. Connect it. Complete the consent, or collect the secrets on your page. Check that the configuration works, for example with a test call to the external system.
6. Report the result. Call POST /v1/integrations/configurations/{configurationId}/ready. If the configuration cannot work, call .../failed with a code and a reason.
7. Send the administrator back. Redirect the browser to return_url.

An app without a setupAddress skips steps 1 to 3 and step 7. It reads its configurations when it starts. It checks each one and reports ready or failed.

What a configuration carries

A business configuration can leave a field empty when the organization configuration has a field with the same key and type. Hydda One then fills it from the organization configuration before it answers. A value saved at the business wins. Your app never merges values itself.

Configuration statuses

You can report failed on a ready configuration, for example when a credential stops working. You can report ready on a failed one once it works again.

When an administrator changes a configuration, its status returns to pending and updatedAt changes. Check the new values and report again.

Rules for callers

Reports are safe to repeat

Reporting ready again changes nothing. Reporting failed again with the same code and reason also changes nothing. Both answer 204.

Keep secrets secret

The configurations list is the only place Hydda One returns secrets, and only to the installation they belong to. Never log them. Never put one in a failure reason, because the administrator reads it.

Connection references

A reference works once, within ten minutes, and only for the installation it was made for. If the administrator starts a new connection, the earlier reference stops working.

Every refused reference gets the same answer: 400 with INTEGRATIONS_CONNECTION_REFERENCE_INVALID. The answer does not say whether the reference was unknown, expired, used, replaced or another installation’s. A refused redeem does not count as the one use.

An administrator who returns before you report sees the configuration as pending. Report as soon as you know the result.

Limits

Read your configurations when your app starts and after each redeem, not before every call. A request over the rate limit gets 429.

Errors to handle

Errors lists every integrations code and its status.