External API: v2.0 Beta
As an organization you want to optimize your time as much as possible and a lot of our customers were doing this by automating their bug bounty program through Intigriti’s external API. Forwarding submissions to internal ticketing systems such as for example JIRA or automated posting with every new release were use cases for the API so far. However, this API (v1.2) was limited by the fact that it was relying on machine-to-machine authentication using ClientID and Secret alone.
The new Intigriti External API v2.0 is looking to change this by introducing a new flow of user authorization and authentication, allowing for the introduction of new API calls as well. This means more options for automating tasks, ultimately leading to a more efficient bug bounty program! Our team (including our researcher community) has done a lot of testing on the API to make sure everything works as intended but of course the best validation of our work is seeing the real life application. Therefore, we want to invite all interested customers to try out v2.0 of our API and encourage integration with this newer version of this new version we developed.
What’s new with v2.0?
- Use of standard OAuth 2.0 protocol
- A user-based authorization flow (instead of machine-to-machine in v1), allowing for a more granular permission set-up and activity logging
- Numerous improvements to existing endpoints
- 8 new read operations and counting, all related to the submission data
- 11 new write operations and counting. This includes:
- Update all submission properties such as the severity, bounty & GDPR features.
- Post internal/external submission message
- Create or delete company submission bonus
What documentation do I need?
How to start using Intigriti’s External API v.2.0?
Contact your Customer Success Manager
Before you can get started doing anything by yourself we will need to enable access to the new version of our API. That’s something your Customer Success Manager can do, so please just reach out to them.
1. Start the Intigriti API integration wizard
Keep in mind that since authorization in v2.0 is user based, the API user will need to have the correct role to be able to passably use certain endpoints. The necessary security requirements will be mentioned in each endpoint in this ReadMe, and will usually refer to the roles in the UI:
- Company Admin
- Program Admin
- Program Editor (either unassigned or assigned to the submission)
- Program Member (either unassigned or assigned to the submission)
- Group Admin (either unassigned or assigned to the submission)
- Group Member (either unassigned or assigned to the submission)
The API user will be the one running through this wizard. Therefore, make sure you’re logged into the right account!
Navigate to Admin > Integrations > Intigriti API > Open configuration.
On this page, find the “Create API configuration” button on the top right:
Important: “Delete API configuration”
If you already have an active API integration, the button on the top right will show “Delete API configuration” in red. A company is currently only allowed one active API integration at a time. To set up a new integration, the existing API set-up must be deleted first. If you have an active integration running in production do not delete the existing credentials. In that case your Customer Success Manager can arrange for access to another environment for beta testing.
2. Fill in the Redirect URL
Redirect URLs are a critical part of the OAuth flow. After a user successfully authorizes an application, the authorization server will redirect the user back to the application. The user will be redirected back to the application with a new authorization code in the URL. As such the redirect URL will contain sensitive information, therefore it’s critical that the service doesn’t redirect the user to arbitrary locations. In the modal that appears, fill in the desired redirect URL and then press “Continue”. Note that the Redirect URL may only start with the http:// or https:// protocols. localhost is not allowed.
3. Receive Client ID and Secret
A Client ID and Secret will be returned. These credentials will grant authorization for the API integration. Make sure to securely store the credentials, then mark and press Close.
4. Ready for authorization!
On the Intigriti external API page, a new line will indicate that the Client ID is now created and active. But before the API integration can be fully utilized, the user from which the API integration has been set up has to be authorized.
5. Authorize user via OAuth 2.0 flow
The user should initially authorize via a standard OAuth 2.0 flow. A user shall be presented the following login screen unless he already has an active session in the same browser through which the authentication request is directed. In that case, authorization should be granted immediately.
Once the user has been authorized, using refresh tokens to retrieve a new pair of bearer and refresh token can keep the session active without having to authorize again.
6. All done, you’re good to go!
The API integration can now be utilized. The rate limit has been capped at 600 requests per minute for read operations, 200 requests per minute for write operations. Why not try some of the new API calls such as:
- Posting a new submission message
- Getting submission payouts
- Updating submission internal reference and internal reference link
What else is cooking?
- Company admin users can see more details of their company members, giving them better options for permission and user management and helping to keep their accounts secured!
- Added Autofocus on verification code field for entering 2FA code! 1 click when logging in ! 😉
- Added tweet previews (including your profile picture) in the email. Now you have no excuse to share your Intigriti profile or bounty 😉
During March, the Product & Engineering team has contributed over 200 trees to the 775 trees that will be planted thanks to our intigriTREE challenge. So much for the cliché of sitting behind the desk all day!
Does the idea of working in a promising, flexible and fulfilling environment inspire you? Discover careers at Intigriti by visiting our careers page or following us on LinkedIn. We look forward to your application!