Viima's APIs currently support two authentication methods: session-based and OAuth2.0 based with the latter obviously being the only method available for external developers.
In order to make API calls from an external system to Viima, you need a user on whose behalf the calls are made and an OAuth 2.0 client for authenticating this user.
User
Currently, our API supports password-based and implicit (currently in private beta) OAuth2.0 authentication flows.
IMPORTANT: When using the password-based flow, you're going to need a Viima user (email + password) to be able to connect to our API. This means that you can't use SSO options, such as a Microsoft 365 account for authenticating with our API. If you have already logged in with SSO before, you can create a password for your user from Viima's login page by choosing "Or login with Viima account", and then "Forgot your password?"
We strongly suggest you add a new user for each integration to keep your access controls simple and atomic. This minimizes the risk of someone else being able to steal your credentials or impersonating you, as well as the impact that such an incident could have should it occur. Please remember to use strong passwords and maintain a regular and frequent password rotation policy. We reserve the right to block access to our APIs for clients in violation of these principles.
The access rights your user has are the same for our APIs, as they are when using the software. So, your user needs to have appropriate levels of access rights to whichever Viima board it is that you'd like to integrate. Thus, Board-specific admin rights are required for the full functionality of many of our APIs.
OAuth 2.0 Client
OAuth clients in Viima are always board-specific. You can manage them from the Integration Settings section of your boards' admin portal, for example, https://app.viima.com/admin/organization/board/#settings/integration.
Currently support for implicit OAuth2.0 authentication flows is in beta, please contact our support for more details.
Getting Started with the APIs
Prerequisite: Make sure the user you have logged in with is the same user you want to create the API client for, and that the user is a Viima account.
Step 1:
Start by clicking "Create new client" and then give a name for your new client. Once you've done this, you can use your Client ID and Client Secret to get an access token and then make additional API requests.
Step 2:
Next, you need to authenticate yourself with the Client ID and Secret you've just received. You'll receive an access token and a refresh token with a successful request.
curl -X POST https://app.viima.com/oauth2/token/ -d "client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&grant_type=password&username=<EMAIL>&password=<PASSWORD>"
Or if you have a valid refresh token:
curl -X POST https://app.viima.com/oauth2/token/ -d "client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>"
Step 3:
You can now start using the API by passing your access token in the request headers. You can try this with the example below.
For a more detailed look into the different available API endpoints, please refer to our interactive API documentation.
Note: Once your session expires, you will either need to log in or use your refresh token to get a new access token. Depend on the nature of your integration, it may be simplest to have the user always log in prior to executing your requests.
curl -X GET https://app.viima.com/api/user/ -H "Authorization: Bearer <ACCESS_TOKEN>"