Sometimes when doing server to server API integrations you may want to make API calls on behalf of another user. This article articles explains the process.
What API Calls Can You Spoof?
You can spoof any APIv2 call you want as long as the user you are spoofing has access to the endpoint.
Pitfalls of Spoofing
Before you decide to use the spoofing functionality make sure you understand the pitfalls.
- Spoofing is a very powerful tool, but can be dangerous too because you are allowing access to other user accounts. Make sure you really need to spoof.
- Don't use spoofing as a workaround for SSO. Think of spoofing as a tool for administrators or server integrations such as automated posts on behalf of users.
- When you spoof as another user then the call will be made completely in the context of that user. This includes permissions. You can only make API calls that the spoofed user could also make.
Enabling API Spoofing
API Spoofing requires the Spoof addon to be enabled. You can enable it in your dashboard under addons. In order to spoof you will need to make API calls with an access token that has admin access (garden.settings.manage). Make sure you have an access token associated with a user that has enough permissions.
Making Spoof Calls
In order to spoof when making an API call you pass the user ID of the user you want to spoof in the
X-Vanilla-Spoof header. Here is an example:
Auhorization: Bearer <Access Token>
These headers will make the API call as user "123" rather than the user that owns the access token.
Spoofing With Smart IDs
The example above shows an integer user ID. This works, but can sometimes be difficult to develop with because you have to look up users before spoofing as them. To get around having to look up users you can use Vanilla's smart IDs to spoof users by name, email address, or SSO ID. Here are some examples:
// Spoof as username "frank"
// Spoof with SAML SSOID
You can look up a user when spoofing with any valid smart ID. For more information on smart IDs check out the Smart ID documentation.