Skip to content

Setup

This page describes what BIOS and a client must do before the client can place an order, as in the happy path scenario.

Open questions: remove before sharing with clients

  • How does the client get the order_id for each order?

Sequence

---
config:
  sequence:
    actorMargin: 26
    width: 96
    height: 44
    diagramMarginX: 12
    diagramMarginY: 12
---
sequenceDiagram
  participant Client
  participant ClientAuth as Client Auth<br/>Server
  participant Webhook as Client Webhook<br/>Endpoint
  participant Auth as BIOS Auth<br/>Server
  participant API as BIOS API
  participant BIOS
  BIOS->>BIOS: 1a. Set up the client's<br/>organization and orders
  BIOS-->>Client: 1b. Client ID and secret
  Client->>ClientAuth: 2a. Create an OAuth client for BIOS
  Client->>Webhook: 2b. Deploy the webhook endpoint
  Client->>Auth: 3a. POST /oauth/token
  Auth-->>Client: 3b. 200 OK with access token
  Client->>API: 4a. POST /webhooks
  API-->>Client: 4b. 201 Created with signing secret

Steps

  1. BIOS onboards the client.
    1. BIOS sets up the client's organization, and an order for each test the client will request.
    2. BIOS gives the client a client ID and secret for the BIOS API.
  2. The client prepares to receive webhook events.
    1. The client creates an OAuth 2.0 client for BIOS in its own auth server, so that BIOS can get access tokens to call the client's webhook endpoint.
    2. The client deploys an HTTPS webhook endpoint that checks each event's access token and signature.
  3. Get an access token.
    1. The client calls the POST /oauth/token endpoint of the BIOS auth server with its client ID and secret.
    2. The BIOS auth server returns a 200 response with an access token.
  4. Register a webhook.
    1. The client calls the POST /webhooks endpoint of the BIOS API with the webhook endpoint's URL and the client credentials from step 2.
    2. The BIOS API returns a 201 response with the webhook's signing secret, which the client stores to verify events.

The access token will expire expires_in seconds after the BIOS auth server issues it. Before then, the client repeats step 3 to get a new token.