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.

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.

Note: The scopes that can be sent with each request are limited to the scopes you setup for your registered app within the Organization 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 Organization Admin, 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:

Direct the user to our authorization endpoint: https://auth.zywave.com/connect/authorize
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.
The server will redirect the user to a URI that you specified in the registered apps section of the Organization 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

Note: An access_token will expire for security purposes. Applications must handle re-authorizing the user when expired.

Profiles

Zywave applications and 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

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.

https://api.zywave.com/profiles/V2.0/Profile/B

A particular profile may be obtained from the following route:

https://api.zywave.com/profiles/V2.0/Profile/B/{id}

When requesting a specific profile, a ProfileToken is included in the response. There are two different ways to provide the user's active profile via the Profile header. Replace the values between the braces with the actual values, e.g. B 1234 or Token eyJhbGciOi...:

Header Key	Header Value
Profile	{TypeCode} {ID}
Profile	Token {ProfileToken}

Implicitly

Note: It is highly discouraged to rely on implicit profile context for any integrations. This section remains for posterity.

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.