OAuth2 / ID Token Request

Getting access to secured API endpoints is easy using industry standard frameworks.

• OAuth2 protocol as the token request and response format.
• OpenID Connect ID Tokens as access_token and refresh_token format.

Depending on the type of application you want to give access and the scopes required, you need end User authorization, which is the default authorization flow.

The API User email and secret created while setting up your API Client can be used to authorize the request.

Setup an API User and API Client Credentials Any customer organization is required to create its own unique API Client and API User. Read more about how to create an API User and client credentials at the following link. https://developers.bedrijfsrooster.nl/docs/create-a-customer-api-user

Learn more about the Authorization Code Flow Get a deeper understaning about the Authorization Code flow at the following link. https://auth0.com/docs/flows/authorization-code-flow

Client Credentials Flow Requirements If your app needs to use the client credentials flow, we might request for specific requirements. Please inform support about your request, which needs to allow your API Client to be able to use this flow.

OAuth2 Authorization Code Flow (default)

To start the authorization code flow send the User browser to the following URL.

https://id.bedrijfsrooster.nl /oauth/authorize?response_type=code&scope=all &client_id={ABC}&state={XYZ}&redirect_uri={URI}

Take into account the following while generating and using this URL.

• Notice that the user facing domain is **id.**bedrijfsrooster.nl
• As scope you can use [all] and should not change this
• Authenticate using the API User email and secret that relate to the API Client
• The redirect_uri must match the one configured when you created your API Client

After successful authentication by the User the browser will be redirected to your URL.

{YOUR_REDIRECT_URI}?code={XXX}&state={XYZ}

Use the code in a JSON POST to the IAM API token endpoint to request a refresh_token.

POST https://api.bedrijfsrooster.nl/api/v1/iam/oauth/token

{
  "grant_type": "authorization_code",
  "audience": "bedrijfsrooster-api",
  "code": "{XXX}",
  "redirect_uri": "{URI}",
  "client_id": "{API_CLIENT_ID}",
  "client_secret": "{API_CLIENT_SECRET}",
}

Take into account the following while calling the token endpoint.

• If your OAuth2 program is not able to post everything, you can provide the audience as URI query parameter.
• The Bedrijfrooster API default audience name is [bedrijfsrooster-api]
• The code will expire within a few minutes and can be used only once
• Of the response refresh and access tokens, prefer to use refresh token

Now you might use the access_token immediatly, but we recommend the following.

• Securely store the refresh_token next to your API User secret and API Client secret
• Securely store and cache an access_token, and check the expiration before reusing
• The access_token / ID Token is valid for about 3600 seconds or 1 hour
• The refresh_token is long lived and should be used to renew an expired access_token
• Use the IAM API /idToken endpoint to exchange the refresh token for an ID Token
• ID Token is identical to access_token and can be used to authenticate

You are now ready to fully access all secure API endpoints with your ID Token.

OAuth2 Client Credentials Flow

If your app needs to use the client credentials flow, we might request for specific requirements. Please inform support about your request, which needs to allow your API Client to be able to use this flow.

OAuth2 Refresh Token Flow

If your app needs to use the refresh token flow, we might request for specific requirements. However, we prefer that you use a refresh_token combined with the /idToken endpoint. More infomration is described in the "Authorization Code Flow" chapter.

Single Sign On Flow

If your app needs to use Single Sign On (SSO), we might request for specific requirements. Please inform support about your request, which needs to allow your API Client to be able to use this flow.