Opal Onboarding API
## Onboarding Overview Unlike many other Opal endpoints, the Onboarding endpoints are only accessible via a special OAuth scope that is not currently offered to Opal customers (i.e. it is internal-use only). The `trial_invites` `POST` endpoint is JSON:API compliant, but the `trial_invites/do/accept` endpoint is capable of serving up either a JSON RPC response or redirecting to a user onboarding web page depending on whether HTML or JSON is specified in the request's `Accept` header. The process of requesting an invitation and accepting it is always two steps: 1. A `POST` request to `onboarding/v3/trial_invites` creates a trial invite and produces an `accept` link that is included in the response body. 2. A user follows the `accept` link in a browser and is redirected into the user setup process OR a client makes an RPC request to the `accept` link and receives a `user_setup` link a user can follow to begin profile setup in a JSON response body. There is optionally a third step. If the `user_setup` link in the `accept` request's response is not used to get the user into their setup flow, a `GET` request to `onboarding/v3/trial_invites/status` can be sent in order to retrieve a `trial_invite` record that surfaces the `user_setup` link as well. ### Setting up a new integration The internal-only process of creating a new onboarding integration starts with creating a new onboarding client. From Opal's Hydra admin CLI, choose the "create onboarding client" option. Fill out the required information and take note of the Client Secret produced near the end of the process. This is the only time that client secret will be accessible. This secret should be saved in Opal's shared Engineering vault in 1Password. Next, a third party integration that creates new Opal trials can be set up with the newly created Hydra client in one of two ways. Either it can make a Client Credentials OAuth 2.0 token request using the client secret and then make authenticated requests with the token it receives in response, or you can set the third party integration up to use Opal's `trial_invites` endpoint as a webhook (see below). #### Webhook usage If you want to create a token and treat it like an API key while using the `trial_invites` endpoint as a webhook, you should request an OAuth token by hand and use that token in the third party integration as a long-lived API key. From the Hydra admin CLI, select the onboarding client you created for the purposes of this integration. Next choose the "Show sample auth URL and curl commands" option. You will get a CURL command like the following: ```shell curl -X POST \ https://login.ouropal.com/oauth2/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d "client_secret=&client_id=onboarding1--742d8aff84759a6c&grant_type=client_credentials&scope=write:onboarding" ``` Replace `` with this client's secret, replace `https://login.ouropal.com` with whichever Opal domain you are working against, and make the request from a shell on your laptop (just needs internet access and `cURL` installed). This will produce JSON similar to the following: ```json { "access_token": "dRGg4JW0F9QIHBnZpkLHWJ7j748AsALcL4_UfmjI0-4.VYbLrAiQzqgrmgXClQhmICP2_7BBEp9OMgKO9lpyUjU", "expires_in": , "scope": "write:onboarding", "token_type": "bearer" } ``` Now take your `access_token` and plug it into an Authorization header for whatever webhook request to `onboarding/v3/trial_invites` your new integration is going to make: ``` Content-Type: application/json Accept: application/json Authorization: Bearer dRGg4JW0F9QIHBnZpkLHWJ7j748AsALcL4_UfmjI0-4.VYbLrAiQzqgrmgXClQhmICP2_7BBEp9OMgKO9lpyUjU ```