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.
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.
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.
access_token
To receive an access_token
, you must do the following:
https://auth.zywave.com/connect/authorize
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_token
will expire for security purposes. Applications must handle re-authorizing the user when expired.
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:
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} |
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.