Introduction

The two hosts, what an Application is, and the first call every integration makes.

The Hydda One API is plain HTTPS with JSON bodies. Every request carries an access token.

Two hosts

The development environment uses idp.dev.hydda.one and api.dev.hydda.one. Credentials from one environment do not work in the other.

Who calls the API

Two kinds of client call the API.

• An Application belongs to one organization. An administrator of that organization creates it and gives you its client_id and a client secret. It gets a token with the client_credentials grant.
• An installed connector is an app an organization installs, such as an ERP or e-signing connector. It signs in with its own private key and gets a token for one installation.

Both get a short-lived access token from the token endpoint. See Authentication.

What a token can reach

A token belongs to one organization. An administrator grants it roles, and each role holds in part of the organization. Hydda One calls those parts operational contexts: the organization itself, a property or a co-working business, for example.

Start every integration by listing the operational contexts the token can act in, with GET /v1/operational-contexts on the identity host. Most other routes take an operationalContextId from that list. Roles lists which role opens which routes.

Conventions

• Bodies are JSON, sent with Content-Type: application/json.
• Ids are UUIDs.
• Times are ISO 8601 in UTC. Dates without a time are YYYY-MM-DD.
• Money is an integer amount in minor units, with an ISO 4217 currency. 12500 in SEK is 125.00 kronor.
• A list that can grow returns a nextCursor. Pass it as cursor to read the next page.
• Every failure returns a problem details body with a machine-readable code. See Errors.