Using offline access and refresh tokens

Purpose

A guided walk-through for using the offline_access scope and refresh tokens to call Zywave APIs without requiring a user to be present and re-authenticate each time.

Background

This page applies only to apps using User-based OAuth 2.0. If your app uses System-based OAuth 2.0 instead, offline_access and refresh tokens aren't relevant. There's no user session to keep alive.

By default, the access token returned from the Authorization Code grant type is short-lived, and the user would need to log in again once it expires. Requesting the offline_access scope changes this: it's applicable to any Zywave API that authenticates using the Authorization Code grant type, and causes the token response to also include a refresh token. That refresh token can then be exchanged for new access tokens going forward, without the user needing to log in again.

Walk-through

Initial setup

When offline_access is requested, the user is always prompted to consent, even if they've consented before. There's no option to remember that consent for future logins.

Ensure your registered app has the offline_access scope enabled, in addition to any other scopes required by the APIs you intend to use
Have your application complete the Authorization Code flow, requesting offline_access along with the scopes for any APIs you intend to access. The resulting token response will include a refresh_token alongside the access_token. Store the refresh token in a secure area, as this will be used to get new access tokens going forward. This refresh token is set up 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 user whose refresh token you obtained above. 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 can be retrieved by calling the current profile API with your access token, 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

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)