Understanding and Managing Profiles

Like most other software-as-a-service offerings, Verdocs is "multi-tenant." Our permission management mechanisms are designed to allow users to perform actions on behalf of more than one organization at a time. This is achieved by separating the concept of a "user" (a single person, with a unique name and identity) from a "profile" (that person, acting on behalf of one organization). Consider the diagram below:

In this scenario, Paige Turner works for Odyssey Gym and regularly creates Liability Waivers for new members to sign. Paige is one person and has one profile, which defines her relationship to Odyssey Gym.

Will Power is one person but has two profiles. Will works for Greene CPAs during the week as an assistant, so he regularly sends IRS e-File Authorizations to clients of the firm. On the weekend, will also works for Odyssey Gym, and thus has also a profile defining his responsibilities there.

"Current" Profile

Although Will Power has two profiles, only one is active, or "current," at a time. This may be changed at any time in the Verdocs Web App by choosing a different organization in the top-left menu, or via an API call:

curl -X POST 'https://stage-api.verdocs.com/v2/profiles/NEWPROFILEID/switch' \
    -H "Content-Type: application/json" \
    -H 'authorization: Bearer ey........Nc'

After switching profiles, calls to list templates, envelopes, or other data will "act as" the new current profile.

Overriding the "Current" Profile

For historical reasons, switching the current profile will return new authentication tokens because they refresh the user's session. However, it is important to note that while tokens contain the user's profile_id, this is only a convenience to help client-side code identify the current profile for the user at the time the token was issued. That may not be the current profile for the user if it is changed later.

Previously issued tokens are not invalidated because there are legacy applications for which this behavior is required. But this can cause confusion for developers new to Verdocs if profiles are being switched regularly because calls may not return the data expected, particularly if you use your personal account when making calls, and change your current profile regularly.

The easiest way to avoid this is to create an "API User" that is only used for API calls. If this user never changes its current profile, you will never encounter this issue. However, in highly dynamic workflows where profiles and even organizations are created via the API rather than manually, there is a header you can set when making calls that will override this default behavior:

curl -X GET 'https://stage-api.verdocs.com/v2/templates' \
    -H "Content-Type: application/json" \
    -H 'authorization: Bearer ey........Nc' \
    -H 'x-ignore-current: true'

Setting this header will instruct our API to disregard the current profile for the user making the call, and use the profile_id encoded in the access token instead.