Technology
How CobraSphere's APIs are built, how traffic reaches the products, and how one sign-in works across them.
This section explains how CobraSphere's systems are built and reached. It describes the principles. Addresses, host names and other details that would only help an attacker are left out on purpose.
API policy
CobraSphere's APIs are not open to customers yet. Access will be by agreement later.
How the APIs are built
The backends behind the CobraSphere products share one way of building an API.
| Part | What it means |
|---|---|
| API Platform | Each backend is built on API Platform, so every API follows the same rules |
| JSON-LD and Hydra | Answers are JSON-LD. Lists and their pages follow Hydra, so a list says how many items it holds and where the next page is |
| OpenAPI | Each API describes its own resources in an OpenAPI description |
| UUIDs | Every record is known by a UUID. A record that several products use keeps the same UUID in each of them. See Shared records |
| Versioned releases | Each backend carries a version number that goes up with every release |
| Errors | An error answer follows the standard problem format (RFC 7807), so it reads the same in every API |
Gateways
Traffic reaches the products along a small number of fixed routes.
- Public traffic. Requests from the internet reach a CobraSphere product only through the public gateway. The gateway sits behind Cloudflare and accepts traffic from Cloudflare only. It passes on named paths only, so anything that is not listed cannot be reached.
- Product to product. When one CobraSphere product calls another, the call goes through a private internal gateway and never leaves the private network.
- Private services. A service that the public does not need has no public address at all.
Sign-in
One CobraSphere ID
A person has one CobraSphere ID and signs in with a one-time code sent to their email address. Every product reads the same person from the identity service. See Identity.
Signing in on another site
A person signed in on the Account console can open another CobraSphere site without a second code.
- The Account console asks the identity service for a one-time sign-in code for that site.
- The browser goes to the site with the code.
- The site's own server swaps the code for its own sign-in.
A sign-in code works once and for about a minute. It is only ever sent to a return address on the identity service's allow-list. Each address on the list must match in full and use https. Preview copies of sites are not on the list, because their addresses are not fixed.
System accounts
Each product's server signs in to the identity service with its own system account, not as a person. Only the system accounts named for a site can swap that site's sign-in codes. An account's key is kept in the product's own protected settings and never in its code.
Why this is public
The reason these pages are open to everyone is set out in Why we publish this.