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.
Required: If using Zywave's v2.x APIs, get the profile ID/profile type code 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 while using refresh tokens, 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).
- For more information on the Profile header, read the documentation on explicit profiles

Making API calls with a refresh token

Note: Zywave strongly recommends using a library for your preferred language or framework for working with OAuth 2.0 patterns. The below are purely for informational purposes.

Example:

      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]"

using System.Net.Http;
using System.Net.Http.Headers;

HttpClient client = new HttpClient();

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://auth.zywave.com/connect/token");
request.Content = new StringContent("client_id=[YOUR_CLIENT_ID]&client_secret=[YOUR_CLIENT_SECRET]&grant_type=refresh_token&refresh_token=[YOUR_REFRESH_TOKEN]");
request.Content.Headers.ContentType = new MediaTypeHeaderValue("application x-www-form-urlencoded");

HttpResponseMessage response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://auth.zywave.com/connect/token"))
    .POST(BodyPublishers.ofString("client_id=[YOUR_CLIENT_ID]&client_secret=[YOUR_CLIENT_SECRET]&grant_type=refresh_token&refresh_token=[YOUR_REFRESH_TOKEN]"))
    .setHeader("Content-Type", "application x-www-form-urlencoded")
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

fetch('https://auth.zywave.com/connect/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application x-www-form-urlencoded'
  },
  body: 'client_id=[YOUR_CLIENT_ID]&client_secret=[YOUR_CLIENT_SECRET]&grant_type=refresh_token&refresh_token=[YOUR_REFRESH_TOKEN]'
});

import requests

headers = {
    'Content-Type': 'application x-www-form-urlencoded',
}

data = 'client_id=[YOUR_CLIENT_ID]&client_secret=[YOUR_CLIENT_SECRET]&grant_type=refresh_token&refresh_token=[YOUR_REFRESH_TOKEN]'

response = requests.post('https://auth.zywave.com/connect/token', headers=headers, data=data)