OpenID Connect (OIDC) is a standard that allows you to authenticate users in Beat’s API using an external user database. In summary, the OIDC flow works like this:

You register an authentication attempt with our API using your client credentials, and you get a handle back.
Our API tells us where to redirect the user in their browser.
When the browser reaches a specific URL, authentication is done.
You exchange the handle you received for a set

Example

You need to get a client ID and client secret for this tenant, and use them in the script excerpts below

CLIENT_ID=
CLIENT_SECRET=
TENANT=fluister

curl -X POST "<https://api.prod.$TENANT.beat.no/v2/oauth2/contexts?partner_id=$TENANT>" | jq

From the response, visit the provided context.url in a browser. Log in using valid credentials from them. Note the context.handle as well, and use it in the next script.

If successful, your browser will redirect to https://api.prod.TENANT.beat.no/v2/oauth2/callback/completed when completed. You can now check if the attempt was successful.

HANDLE=

[curl -X POST "<https://api.prod.$TENANT.beat.no/v2/oauth2/token>" \\
  -d "client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&grant_type=openid_handle&handle=$HANDLE" | jq](<https://beattech.notion.site/ffd8151b664f418486c82825122453aa>)

From this you will get a response containing an access token and a refresh token, as a regular authentication.

Custom redirect URL

It is possible to use a custom redirect URL, provided that the redirect URL is pre-approved by Beat. Beat will need to know the domain name allowed to use for redirect URLs, and confirm that this has been correctly configured.

To use a custom redirect URL, provide it in the POST call to create the context.

Remember that the redirect_url parameter needs to be URL-encoded.

</aside>

CLIENT_ID=
CLIENT_SECRET=
TENANT=fluister

curl -X POST "<https://api.prod.$TENANT.beat.no/v2/oauth2/contexts?partner_id=$TENANT&redirect_url=https%3A%2F%2Fexample.com%2Foauth2%2Fcompleted>" | jq

Once the user is redirected to that URL, you can assume the context can be used to generate an access token as before.