Setting up a service account

Purpose

A guided walk-through for setting up a service account for Zywave APIs through the use of refresh tokens and offline access

Background

Zywave API V2.x is focused on accessing APIs on behalf of a user. In scenarios where it is desired to use the APIs without the direct involvement of a user a service account can be created to make API calls on behalf of.

Walk-through

Initial setup

• Ensure your registered app has the offline_access scope enabled in addition to any other scopes required by the APIs you intend to use
• Recommended: Create a user specifically for the service account. Managing this as a separate user allows access/permissions to be controlled just for API access.
• Get the initial tokens. The Testing API Calls page has a detailed walk-through using the Insomnia API client. When entering the scopes, be sure to include offline_access along with the scopes for any APIs the service account is intended to access. Once authenticated (using the login for the service account created above), save the refresh token in a secure area as this will be used to get new access tokens when making API calls. This refresh token is setup for one-time use only and will expire after 30 days or once used. As a result, when the refresh_token is used to retrieve a new access_token and refresh_token, the new refresh_token will need to be stored for subsequent use. As always, Zywave continues to recommend consumers use OAuth-compliant libraries to avoid misconfiguration issues.
• Get the profile ID or token for the service account user. Zywave supports a concept of multiple "profiles" (permission sets) being available to a user. In order to utilize Zywave API V2.X it is necessary to specify which profile to use for each API call. This information for the service account can be obtained the same way as the previous step by calling the current profile API using typeCode B (B is the typeCode for 'Broker', which is another term for AgencyUser).

Making API calls with a refresh token

• Using your valid refresh token, fetch a new access token

        curl --request POST \
          --url https://auth.zywave.com/connect/token \
          --header 'Content-Type: application/x-www-form-urlencoded' \
          --data client_id=[YOUR_CLIENT_ID] \
          --data client_secret=[YOUR_CLIENT_SECRET] \
          --data grant_type=refresh_token \
          --data refresh_token=[YOUR_REFRESH_TOKEN]
      

• This will return a new access token (valid for 60 minutes) and a new refresh token (valid for a new 30 day window)
• Use the new access token to call Zywave APIs. Be sure to also set the Profile header for the profile of your service account created in Initial Setup (value is either 'Token ' or ' '. Without this header the calls to the API will not have the necessary permissions to access your data.