Birdview offers a flexible API that supports OAuth2 authorization and can be easily tested through Swagger or third-party tools such as Postman. This guide explains the basic setup for both approaches.
1. Set up an OAuth client
To get started, you must create an OAuth client in Birdview (see the KB article for the detailed instructions at https://help.birdviewpsa.com/hc/en-us/articles/9155019022605-OAuth-clients-2-0):
● Go to:
[host]/integrations/oauthclients
where [host] is your Birdview URL.
● Click Add Oauth clients
● Ensure the following options are enabled:
○ Automatic Consent Grant.
○ Allow client credentials grant authorization.
2.1. Using Swagger
Swagger provides an interactive interface to explore and test the Birdview API.
Steps:
1. Open the Swagger in your Web browser:
[host]/api/
2. In the Select a definition drop-down list, select "v2".
3. Click the Authorize🔒button in the top right.
4. In the authorization popup window, you can use one of the two available authorization methods, for example
○ Use the OAuth2 Access Code grant.
○ Enter your client_id and client_secret.
○ Click Authorize buton.
5. Once authorized, you can test all available endpoints directly in the browser.
2.2. Using Postman
To access the API via Postman, follow these steps:
○ Open the Authorization tab.
○ In the Auth Type drop-down list, select OAuth 2.0.
○ Enter [host]/OAuth2/Token in the Access Token URL field. (where [host] is your Birdview URL)
○ Enter your Client ID in the Client ID field.
○ Enter your Client secret in the Client Secret field.
○ Enter user:[x] in the Scope field. (where [x] is the Birdview user ID)
○ Click Get New Access Token button.
○ Click Use Token button.
2.3. Using other tools
The Authorization Request to be sent:
POST [host]/OAuth2/token Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=[clientID]&scope=user:[user]&client_secret=[clientSecret]
● Replace:
○ [host] with your Birdview URL
○ [clientID] with your OAuth client ID
○ [clientSecret] with your OAuth client secret
○ [user] with the target user ID (not email)
Response:
You’ll receive an access token, which you can then include in the Authorization header for subsequent API requests: Authorization: Bearer <access_token>
This setup allows you to integrate and test the Birdview API in both development and production environments using tools of your choice.