External Two squares, one overlapping the bottom one. Top square has an arrow pointing away, as if leading you away

Authentication

Do you need to authenticate?

For requests made on behalf of a user, the Zywave API requires authentication. Put another way, if a user would have to log in to a Zywave product to access or modify a piece of data, authentication is required to access or modify that piece of data using the Zywave API.

This page documents User-based OAuth 2.0. If your app uses System-based OAuth 2.0 instead, the steps below don't apply. See Authorization methods for more.

Scopes

The OAuth 2.0 specification allows you to specify the scope of the access you are requesting from the user. All applications have basic access by default, but if you plan on asking for extended access such as reading or writing account or account contact data, you will need to specify these scopes in your authorization request.

The scopes that can be sent with each request are limited to the scopes you setup for your registered app within the Zywave Admin tool.

Authenticated requests require an access_token. These tokens are unique to a user and should be stored securely. Token lifespans are set in the Zywave Admin tool, but may be revoked before scheduled for security or other purposes.

Receiving an access_token

To receive an access_token, you must do the following:

  1. Direct the user to our authorization endpoint: https://auth.zywave.com/connect/authorize
  2. If the user is not logged in, they will be asked to log in and to confirm that they would like to grant your application access to their Zywave data. Your application will only have access to Zywave data that the user has access to.
  3. The server will redirect the user to a URI that you specified in the registered apps section of the Zywave Admin tool. Take the provided code parameter and exchange it for an access_token by POSTing the code to our access_token url: https://auth.zywave.com/connect/token

access_tokens expire and applications should handle re-authorizing the user.

Profiles

Profiles and the documentation below only apply to Zywave's v2.x APIs. Zywave's v3.x APIs do not require profiles.

Zywave applications and v2.x APIs utilize profiles in order to authorize users. Profiles are a collection of permissions for an organizational unit, such as an agency or account, that are linked to a user. Zywave APIs require that a profile be resolved for a user for any given request. This may be accomplished in one of the two following ways:

Explicitly

The method documented here is the recommended method for properly calling Zywave's v2.x APIs.

It is possible to indicate a specific profile to use in an API request. To obtain a list of profiles that an authenticated user has access to, one may invoke the following GET call, supplying an access_token in the header.

A particular profile may be obtained from the following route:

When requesting a specific profile, a ProfileToken is included in the response.

ID and type code

The combination of a profile's ID and TypeCode can be added to an API request in the following format:

Profile: {TypeCode} {ID}

Replace {TypeCode} with the desired profile type code and {ID} with the desired profile ID.

Profile token

Alternatively, a profile's ProfileToken can be added to an API request in the following format:

Profile: Token {ProfileToken}

Replace {ProfileToken} with the ProfileToken value returned from the profile request.

Implicitly

Implicit profile resolution is NOT supported when using offline_access and refresh tokens. You MUST provide explicit profile header values.

Implicit profile resolution is not recommended. It can manifest in unexpected profile resolution and errors.

A user will always have an active profile for their session. If no profile context is specified for an API request, the API will resolve the active profile. A user's active profile may change based on their activity, however it is most often most desired that API requests are made with the active profile.