We are excited to announce the release of the next version of the CyberGRX API!
As additional functionality is completed during 2H 2023 and 1H 2024, information in this article will be updated along with updates to the OpenAPI Spec.
For members using our API V1 functionality, we encourage you to begin the migration to API V2 as soon as possible. The API V1 End-of-Life is planned for March 31, 2024.
Table of Contents
-
Manage Your Third-Party Portfolio
-
Add a company in the CyberGRX Exchange to your third party portfolio
-
Add a company to the CyberGRX Exchange and to your third party portfolio
-
View the tags associated with companies in your third party portfolio
-
Update information on a company in your third party portfolio
-
Request a third party complete and authorize a CyberGRX questionnaire
-
API Getting Started
The CyberGRX V2 APIs allow customers to create and automate workflows to support your Third Party Risk Management program.
Here are the high-level quick start steps for using the CyberGRX API:
- Explore the technical documentation for information about what endpoints and fields are available on our OpenAPI Spec
- Contact your CyberGRX representative to provision credentials for you in the Demo or Production environments
- Verify your credentials with the built in OpenAPI auth GET TOKEN
- Experience the data available with OpenAPI’s “TRY” functionality
- Review your current TPRM process and decide what level of integration and automation is best for your business!
- Need more info? Keep reading below to get answers to all your API related questions.
API Access & Information
OpenAPI Spec
CyberGRX uses OpenAPI Specification (fka Swagger RESTful API Documentation Specification) to document our REST APIs.
View the OpenAPI Spec for the production CyberGRX API.
View the OpenAPI Spec for the demo / test CyberGRX API.
API Authentication
At CyberGRX, we are all about keeping your data secure! You must have a CyberGRX account and credentials with the appropriate permissions to access the CyberGRX APIs.
API Credentials
Contact your CyberGRX representative to generate API V2 credentials in either Demo or Production. A client id and client secret associated with your company account will be created and shared with you via an encrypted email.
If you do not currently have access to an account in the Demo environment, one will be created for you at this time. While you can experience production-like functionality in demo, we do not have real company and assessment information in demo. It has been seeded with “fake” company records and completed assessments to enable end to end testing.
NOTE: Currently, there is not a way to self-serve the creation of API V2 credentials from the CyberGRX Portal. That functionality is planned to be delivered in 2024.
Your API credentials carry many privileges, so be sure to keep them secure. Do not share your secret API credentials in publicly accessible areas such as GitHub, client-side code, and so on.
API Tokens
To make a call to the CyberGRX REST API, you need an API token. We setup the OAuth 2.0 API authentication mechanism to provision API tokens for you. Once you have received your API credentials, verify them with the built in OpenAPI auth GET TOKEN
Tokens are valid for 24 hours and should be reused by the same application during that time window. Token end times are encoded into the token and can be checked prior to using the token so a new one can be generated. Decoding the token can be done with a standard library to view the “issued at” (iat) and the “expiration” (exp) timestamps.
Otherwise, once a token expires the call to the endpoint will fail authentication. If you generate a new token before the expiration has passed, the previous token will still work through its expiration timestamp.
API Scopes
You add scopes to your token when generating it. By default, no scopes are assigned when provisioning a token. Select only the necessary scopes for your planned integration to limit data access. Data that is not within one of the selected scopes will not be accessible to the API token.
In order to see which scopes are required to call an endpoint, refer to the below table:
| API Endpoint | Required Scope |
| Company Endpoints | |
| GET /v2/company/companies | read:company |
| GET /v2/company/companies/{company_id} | read:company |
| Portfolio Endpoints | |
| GET /v2/portfolio/third-parties | read:portfolio |
| POST /v2/portfolio/third-parties | write:portfolio |
| GET /v2/portfolio/third-parties/{company_id} | read:portfolio |
| PUT /v2/portfolio/third-parties/{company_id} | write:portfolio |
| DELETE /v2/portfolio/third-parties/{company_id} | write:portfolio |
| PATCH /v2/portfolio/third-parties/{company_id} | write:portfolio/tags |
| POST /v2/portfolio/third-parties/{company_id}/requests | write:portfolio |
| GET /v2/portfolio/tags | read:portfolio/tags |
| Reporting Endpoints | |
| GET /v2/portfolio/third-parties/{company_id}/risk-navigator/{framework_id} | read:portfolio-findings |
| GET /v2/reporting/frameworks | read:frameworks |
| GET /v2/reporting/frameworks/{framework_id} | read:frameworks |
| GET /v2/reporting/framework-controls/{framework_id} | read:frameworks |
| GET /v2/reporting/priority-third-parties/{framework_id} | read:portfolio-findings |
| GET /v2/reporting/risk-registry-priorities/{framework_id} | read:portfolio-findings |
Base URL
The CyberGRX REST API base URL is as follows:
- Production: https://api.cybergrx.com
- Demo/Test: https://demo-api.cybergrx.com
The CyberGRX authentication base URL is different since we leverage AuthO 2.0 to manage authentication, token create and scope permissions.
- Production: https://cybergrx-production.us.auth0.com
- Demo/Test: https://cybergrx-demo.us.auth0.com
All requests to the CyberGRX API must use TLS protocol version 1.2 in order for the request to be successfully sent.
Time Zone
All dates and time zones available via the API are presented in Coordinated Universal Time (UTC). You may notice a difference in the day or timestamp in the CyberGRX UI because that display is localized based on your set time zone.
If you want to convert the UTC dates to local time prior to presenting to your users, there are standard libraries available.
Pagination
We have one style of pagination you will see in the endpoint to get the list of companies in your third party portfolio.
In the response, you will see “total” which represents the total number of results available, even if they are not all returned in the response.
You can control how many records are returned in the response by setting the “limit” parameter. There is a max set by CyberGRX.
If you turn the “limit” up and the “total” is still showing a number higher than the limit, you can iterate through the result set by calling the endpoint again and incrementing the “offset”.
Filtering
Several of the endpoints for the CyberGRX API allow for filtering. Filtering is optional.
For multiple values of the same filter type, append the filter name and selected values with “&” separating them. Do not use comma delimited lists or new line for multiple values
Example: Tags=123&Tags=345&Tags=XXX
Rate Limits
The CyberGRX API is rate limited. Users can make up to 5 requests a second. Information about rate limits will be returned in the response headers.
API Features & Functionality
API Overview
The CyberGRX V2 APIs allows members to create and automate workflows to support your Third Party Risk Management program.
FUTURE: Planned roadmap projects will allow members to view their own Risk Profile via API, view your Customer portfolio and share your risk profile with a Customer.
Interact with the Exchange
Search for companies in the CyberGRX Exchange
Search for companies in the CyberGRX Exchange by name or domain. Optionally filter the results by Country Code. Provides public company firmographics, third party relationship flag, and available assessment information to identify a company on the exchange.
The main data point to save is the company_id – that is the GRX ID for a company and is used in all the subsequent API calls as the identifier for that company.
The domain is the best way to search. If you search by name and domain the system is actually doing 2 separate searches and presenting the mixed results back to you ranked on match strength. If you want to completely automate adding a new company to your third party portfolio, pass in both name and domain and take the top result by setting the limit to 1.
Want to know more about using Company Search? Check out this article for more information.
View a company in the CyberGRX Exchange
GET /v2/company/companies/{company_id}
If you already have a GRX company_id stored, you can fetch that company to view public level company firmographics, third party relationship flag, and available assessment information for a company on the exchange.
Use this endpoint if any other endpoint gives you an error on the company_id to ensure you have a correct GRX ID saved. Also use this to pull back address information on a company if needed since the GET TP endpoint does not return the company’s address.
Manage Your Third-Party Portfolio
Add a company in the CyberGRX Exchange to your third party portfolio
PUT /v2/portfolio/third-parties/{company_id}
You have found your vendor on the CyberGRX Exchange. (And it looks like they might already have a completed attested assessment, sweet!) Now it is a simple step to use the company_id returned in the company search to add that company to your third party portfolio in order to unlock additional risk information.
Add a company to the CyberGRX Exchange and to your third party portfolio
POST /v2/portfolio/third-parties
If you have searched for a company on the CyberGRX Exchange and have not been successful in finding the vendor you are looking for, you can request to add a new company to the CyberGRX Exchange and also to your third party portfolio with this endpoint. Requires company name, domain and country ISO2 code. The remaining address elements are strongly encouraged to be provided if known as it feeds into our company deduplication and enrichment efforts.
Remove a company from your third party portfolio
DELETE /v2/portfolio/third-parties/{company_id}
Added the wrong company? No longer doing business with a vendor? Declutter your third party portfolio by removing that company; simply pass in the company_id to this endpoint and that company will no longer be in your third party portfolio.
If you tried to call the GET /v2/portfolio/third-parties/{company_id} again with the same company_id, it would now return an error. If you used that company_id to do the more general GET /v2/company/companies/{company_id}, you should see the “in_third_party_portfolio” set to false.
NOTE: If you have any requests for data currently in progress, those requests will be cancelled. You will lose access to data from previously completed requests and authorized assessments as well. Even if you add the company back to your third party portfolio, you will need to re-request access to view attested information.
View the companies in your third party portfolio
GET /v2/portfolio/third-parties
Now that you are done with all the searching, adding and removing of companies, let’s see who is currently in your third party portfolio. View the companies in your third party portfolio, filterable by several elements such as Tags, Inherent Risk, and Custom ID. Provides third party relationship metadata, request and authorization status, available questionnaires and dates, and high level risk information for analysis and prioritization.
To understand how to interpret the data provided on a third party, read the Third Party Management – Use Case Guide section below.
View the tags associated with companies in your third party portfolio
View the tags currently associated with companies in your third party portfolio. Use this information to filter and find third parties via GET /v2/portfolio/third-parties
View a company in your third party portfolio
GET /v2/portfolio/third-parties/{company_id}
View a company in your third party portfolio by its GRX Company ID. Provides third party relationship metadata, request and authorization status, available questionnaires and dates, and high level risk information for analysis and prioritization.
To understand how to interpret the data provided on a third party, read the Third Party Management – Use Case Guide section below.
Update information on a company in your third party portfolio
PATCH /v2/portfolio/third-parties/{company_id}
Update information on a company in your third party portfolio by GRX ID. Manage tags associated with a third party. Set or update the custom id associated with a third party. Use this information to filter and find third parties via GET /v2/portfolio/third-parties
Request a third party complete and authorize a CyberGRX questionnaire
POST /v2/portfolio/third-parties/{company_id}/requests
Request a third party complete and authorize access to the specified CyberGRX questionnaire with the option for validation. A third party contact must also be provided.
Prior to placing a request for an assessment, check if that vendor already has an attested assessment on the Exchange. If you order that tier or lower, the vendor only has to authorize the release of the results to you. If you order a higher tier or if the vendor does not have any assessment on the Exchange yet, that vendor must first completed the assessment in order to authorize the release of the results to you.
NOTE: It is possible that the contact you provided will not be the one returned in the GET TP call. The contact provided at this time is the “Assessment Owner” and is the user determined by CyberGRX to be the contact most likely to be able to action on your request.
Want to know more about the assessment tiers? Check out this article for more information.
Check to see if a request has been fulfilled
Once a request for an assessment has been placed on a company in your Third Party portfolio, you can use either the GET /v2/portfolio/third-parties/{company_id} or GET /v2/portfolio/third-parties to check if that request has been fulfilled.
There are two milestones that must be completed for a request to be fulfilled. The company must authorize you to view their data and the company must complete and attest the questionnaire tier. If you requested validation, then a third activity also needs to be completed where the company uploads their evidence documents and CyberGRX Assessors reviews the evidence to makes determinations if it substantiates the vendor’s claims.
At a higher level, the field “available_in_portfolio” will show you when you have access to an Attested questionnaire or a Validated questionnaire and a request has been fulfilled.
For more detailed information, the section “request_status” provides information about that status and the authorization for access to the data while the section “data_available_in_exchange” provides information about the state of completed and validated questionnaires.
Request_access_status
- Requested: The company has not yet responded to your request.
- Approved: The company has authorized you to view their attested data for the questionnaire tier and validation requested. This field and status alone does not signify that the request has been fulfilled yet as the company may still need to finish the questionnaire and validation may need to be completed.
- Denied: The company has rejected your request to view their attested data for the questionnaire tier and validation requested.
Data_available_in_exchange
- If the questionnaire_name and validation are at the same level or a lower tier as the “request_status” questionnaire_name and validation, you know that the vendor already has a completed assessment on the exchange and you are only waiting for “request_access_status” to be updated to Approved
- If the questionnaire_name and validation are at a higher than the “request_status” section questionnaire_name and validation, then the vendor must complete the additional questions and validation process (if requested). Once that is done you will see the new tier and dates reflected here since this section always shows the highest available tier on the exchange.
- If this section is null, then the vendor has no questionnaire completed on the exchange and must finish answering all the questions for the requested tier and attest for that information to populate for this section.
- If you requested a validated questionnaire, it is possible that you will see a questionnaire with an attestation date prior to the validation being completed.
Access Your Third Party Risk Information
Third Party Risk Profile
Once a company has been added to your Third Party portfolio, you can use either the GET /v2/portfolio/third-parties/{company_id} or GET /v2/portfolio/third-parties to understand the risk profile for a company.
The “available_in_portfolio” field indicates at a glance what risk data is available to you at your third party portfolio level.
Inherent_Profile | Predictive Profile | Attested Profile | Validated Profile
- An Inherent Profile is set when predictive data is not available for the company and when there is no request for an assessment, or when there is a request that is not yet approved and completed.
- A Predictive Profile is set when predictive data is available for the company and when there is no request for an assessment, or when there is a request that is not yet approved and completed.
- An Attested Profile is set when the third party approves the request and attests the associated assessment. For non-validated assessments, the request is considered complete at this point. For assessments with validation pending, this status is displayed when the request is in the validation process but validation has not yet been completed.
- A Validated Profile is set when the third party has approved the request and attested the assessment associated with that request and an assessor has completed the validation process and is only applicable to assessments with validation
Inherent Risk Profile
As soon as a company is added to your third party portfolio, you will have access to Inherent Risk data, powered by the CyberGRX “Auto Inherent Risk” feature.
Inherent Risk describes risk when all cybersecurity controls fail or are missing. It provides a worst case scenario view for engaging with a third party.
There is a section of the company response “inherent_risk” that has the following fields:
inherent_risk_score
- Returns a number from 0.00 to 100.00
- This score is not static and is subject to change daily based on a variety of inputs
- The score is provided to allow custom thresholds for classification if you would prefer to calculate your own bands
inherent_risk_rating
- Returns a string to provide the CyberGRX interpretation of the inherent_risk_score
- The rating provided is the CyberGRX standard classification - CyberGRX is currently using a 3 band of High/Medium/Low
- There are future plans to move to a 5 band in 2024
impact_status
- Returns “CONFIRMED” if you have completed the Impact Questionnaire for the third party
- Returns “UNCONFIRMED” if you have not yet completed the Impact Questionnaire for the third party and are instead seeing the score and rating based on our “Auto Inherent Risk” feature
What to do next?
If “available_in_portfolio” = Inherent_Profile
You can complete the Impact Questionnaire to fine tune the Inherent Risk and ensure it is reflecting how you do business with and rely on that vendor. The Impact Questionnaire API V2 is underway and will be released in Q4 2023.
You can wait for Predictive to be generated for that company. Predictive results are typically available within 2 weeks. See the section “Predictive Risk Profile” for more info.
Depending on the inherent risk of the vendor and your business process, you can request an assessment and wait for it to be completed and authorized to get access to Attested information from the vendor. See the section “Request a third party complete and authorize a CyberGRX questionnaire” for more info.
Want to know more about inherent risk? Check out this article for more information.
Predictive Risk Profile
As soon as an existing company on the CyberGRX Exchange is added to your third party portfolio, you will have access to Predictive Residual Risk data, powered by the CyberGRX Predictive Model.
If you added a new company to the CyberGRX Exchange and to your third party portfolio, the Predictive data may take a while to be generated. Predictive results are typically available within 2 weeks.
Residual Risk describes risk when cybersecurity controls are in place and is what remains of Inherent Risk after the controls assessment answers predict what is mitigated. The score is provided to allow custom thresholds for classification.
There is a section of the response “residual_risk” that has the following fields:
predictive_residual_risk_score
- Returns a number from 0.00 to 100.00
- This score is not static and is subject to change daily based on a variety of inputs
What to do next?
If “available_in_portfolio” = Predictive_Profile
You can dig deeper into the details of the Predictive Assessment results that support the higher level Predictive Residual Risk score. See the section “Assessment Results” for instructions on how to pull and understand the detailed Predictive Results.
Depending on the inherent risk of the vendor and your business process, you can request an assessment and wait for it to be completed and authorized to get access to Attested information from the vendor. See the section “Request a third party complete and authorize a CyberGRX questionnaire” for more info.
Want to know more about residual risk? Check out this article for more information.
Attested Risk Profile
After you have requested an assessment and that vendor has completed and authorized you to view the assessment, you will have access to Attested Residual Risk data.
Residual Risk describes risk when cybersecurity controls are in place and is what remains of Inherent Risk after the controls assessment answers tell us what is mitigated. The score is provided to allow custom thresholds for classification.
There is a section of the response “residual_risk” that has the following fields:
attested_residual_risk_score
- Returns a number from 0.00 to 100.00
- This score is not static and is subject to change daily based on a variety of inputs
What to do next?
If “available_in_portfolio” = Attested_Profile
You can dig deeper into the details of the Attested Assessment results that support the higher-level Attested Residual Risk score. See the section “Assessment Results” for instructions on how to pull and understand the detailed Attested Results.
Want to know more about residual risk? Check out this article for more information.
Validated Risk Profile
A validated profile will only ever be available if you had requested a validated assessment for that vendor. This profile will be available after the company has completed and attested the assessment, submitted evidence documentation, and the CyberGRX Assessors reviewed the documentation and made determinations if the evidence validates the critical controls.
NOTE: Validation results do not influence the Attested Residual Risk data.
What to do next?
If “available_in_portfolio” = Validated_Profile
At this time you can pull the “Assessment Results” again and additional fields will be populated. See the section “Assessment Results” for instructions on how to pull and understand the detailed Validation Results.
Assessment Results
GET /v2/portfolio/third-parties/{company_id}/risk-navigator/{framework_id}
View assessment and risk information for a company in your third party portfolio for a specified framework. Choose to view predictive or attested assessment results depending on what data is authorized and available in portfolio in order to analyze and prioritize gaps for risk mitigation.
If “available_in_portfolio” = Inherent_Profile: Assessment data does not yet exist to be pulled via this API.
If “available_in_portfolio” = Predictive_Profile: Predictive assessment data exists and can be pulled via this API. In order to view the predictive data, use the input parameter calculation_basis = Predictive_Profile
If “available_in_portfolio” = Attested_Profile: Attested assessment data exists and can be pulled via this API. Predictive assessment data is also available. In order to view the attested data, use the input parameter calculation_basis = Attested_Profile
If “available_in_portfolio” = Validated_Profile: Validated and Attested assessment data exists and can be pulled via this API. Predictive assessment data is also available. In order to view the validated data, use the input parameter calculation_basis = Attested_Profile
After deciding what framework to use and the calculation basis, you will get the following assessment results information:
Every framework selected has one or more framework controls. The results are organized by the framework controls first with information about each one along with their score. Each framework control is supported with information on the list of CyberGRX controls, and associated information, mapped to the framework control.
framework_control_name
- The framework specific control name, label or identifier
framework_control_description
- The framework specific control description to elaborate on what is being considered and evaluated
framework_control_group
- The framework specific group that the framework control is associated with for organization and filtering purposes
framework_control_score
- Weighted average score that is derived from the mapped CyberGRX question(s) score(s) and represents how well a framework control is covered
cybergrx_controls
- This section shows the list of CyberGRX controls that were mapped to the framework control
- There could be 0, 1 or many CyberGRX controls mapped depending on the context of the framework control
question_number
- This is the unique identifier for the CyberGRX question on the assessment
question_name
- This is the high-level name / topic for the CyberGRX question on the assessment
question_prompt
- This is the full question text that was displayed to the third party as they were answering the CyberGRX assessment
question_type
- Shows the relationship of the CyberGRX question to the associated framework control
- Primary – indicates one to one matching of the CyberGRX question to the Framework control
- Supporting – indicates that the CyberGRX question will typically cover an aspect of the Framework control but not the control in its entirety
question_score_basis
- Describes the means by which the scores were derived for each control. Values may be any of the following:
- Attested Metrics – the control score is based on Tier 1 answers and includes strength, coverage, and timeliness fidelity
- Attested Control – the control score is based on Tier 2 answers at a Yes/No fidelity
- Attested NA – the control was answered with a 'Not Applicable' response
- Predictive Control – the control score is a predicted value
- Unavailable – neither predictive or attested results are available for this control
question_score
-
The attested or predicted effectiveness of the CyberGRX control
-
Tier 1 assessments range from 0-100
-
Tier 2 assessments are credited with 0 for "No" answers and 85 for "Yes" answers
-
Predictive outcomes range from 0-85
-
The score will be null if the control answer is "NA" or Unavailable
answer_state
- Answer states for the CyberGRX question presented to the vendor
- Yes – the company confirmed they do have the CyberGRX control in place
- No – the company confirmed they do not have the CyberGRX control in place
- NA (Not Applicable) – the company confirmed that the CyberGRX control was not applicable to them
- Unavailable – The company did not have this control in the version of the questionnaire they answered
- Empty / Null – If calculation_basis = Predictive_Profile this field will be null since Predictive assessments do not include an answer state from the company
question_comment
- Third Party comments on the CyberGRX Control if provided
- If the answer_state = NA, then comments are required to be provided by the company
- If calculation_basis = Predictive_Profile, this field will be null since Predictive assessments do not include comments from the company
finding_severity
- Finding severity refers to the identification of a security, policy, or management weakness at the control level. The determination severity is based on a combination of the control’s effectiveness and classification, with those deemed critical or instrumental in preventing MITRE ATT&CK scenarios given extra scrutiny
- High, Medium or Low
- Empty /null – no finding severity for the given control
mitigation
- Provides suggested approaches, technologies, or standards that help improve the control, establish best practices, and reduce the risk of compromise
validation_status
- Describes the validation state for each mapped CyberGRX Control
- Not Applicable – control is not a CyberGRX 60 Critical Control; or validation was not included with your request; or if calculation_basis = Predictive_Profile
- Pending Review – CyberGRX Analysts are in the process of evaluating evidence provided by the Third Party; will only show if “available_in_portfolio” = Attested_Profile and validation was included with your request
- Not Validated – evidence provided was inadequate to determine if the control was in place; will only be an option if “available_in_portfolio” = Validated_Profile
- Validated – all of the validation criteria has been met for this control; will only be an option if “available_in_portfolio” = Validated_Profile
- Not Selected – CyberGRX 60 Critical Control that the third party stated they do not perform (i.e. 'No' answer state), therefore validation is not required; will only be an option if “available_in_portfolio” = Validated_Profile
evidence_type
- Describes the type of evidence that was provided by the third party to validate a control
- Written – evidence in a narrative documentation format. Examples include policies, procedures, emails, etc.
- Demonstrated – any type of primary, technical evidence. Examples include actual live demonstrations, screenshots, exports, etc.
- Verbal – any evidence which is self-attested. Examples include discussions, written notes or explanations, previously completed self-assessments, etc.
- No Evidence – evidence was not provided by the third party
- Not Applicable – control is not a CyberGRX 60 Critical Control; or validation was not included with your request
Want to know more about assessment results? Check out this article for more information.
Get the list of available frameworks
Get the list of available CyberGRX Frameworks, Standard Frameworks, Threat Profiles, and Industry Profiles. If applicable, Licensed Content and Custom Frameworks will also be returned. Store the framework_id to be used as the input parameter for the Risk Navigator or the Portfolio Risk Findings.
Don’t know where to start? We recommend using our “CyberGRX Assessment – Risk Domains” framework as it returns the entire CyberGRX Assessment organized by Risk Domains.
Want to know more about frameworks? Check out this article for more information.
Comments
0 comments
Article is closed for comments.