  Guides Subscribe to updates Go to app

Using the Wiz API Search Ctrl+K

Using the Wiz API



With the Wiz API, you have the power to programmatically perform quite literally every task
and action available within Wiz. You can perform actions such as bulk add connectors, mimic
UI behavior in textual format, or perform complex data manipulation operations.

• Authentication—You must first set up a service account with appropriate permissions

• The GraphQL endpoint—All API calls are sent to the GraphQL endpoint
• Communicating with GraphQL
• Examples
• API Recipes—Annotated example scripts you can use in your own environment

� You can watch our webinar on Using the Wiz API.

Authentication
To create a Service Account, you must be logged in as a Wiz user with Write (W) permission
on service accounts. Project-scoped roles can create Service Accounts only on their own
Projects.

Step 1: Create a Service Account

Step 2: Generate an OAuth token

Create a Service Account

Before getting an API token, first create a new Service Account that represents the calling
machine interface (a script, or an integration system). A Service Account is like a regular user
in the system, except it uses the API to interact with Wiz, instead of the portal.

Learn how to create a Service Account.

Generate an OAuth token

To communicate with the Wiz GraphQL server, you need an OAuth token with the right scopes
(permissions to make the necessary queries/mutations).

To access the API, you must request an Access Token. To do so, POST to the token URL with
the required parameters.

1. To get your token URL:

i. Go to Settings > Service Account.
ii. The token URL is near the top of the screen.

2. Choose your IdP (identity provider) and add the relevant parameters:

Pick your IdP � Cognito Auth0

 If your URL is auth0.gov.wiz.io use the Auth0 parameters.

If your URL is auth.gov.wiz.io use the Cognito parameters.

Parameters

Parameter
Description
Name

grant_type Set this to "client_credentials".

Your application's Client ID. You can find this value on the Settings >
client_id
Service Accounts page.

Your application's Client Secret. You can find this value on the Settings
client_secret
> Service Accounts page.

audience Set this to “beyond-api” or "wiz-api" depending on your IdP.

Response
If successful, you'll receive a HTTP 200 response with a payload containing access_token ,
refresh_token , token_type , and expires_in values:

JSON

{
“access_token”: “eyJr….Eg”,
“refresh_token”: “eyJj….Bw”,
“expires_in”: 86400,
“token_type”: “Bearer”
}

 The parameter refresh_token is only relevant for Cognito IdP.

For more details on generating access tokens and validation process, see the OAuth0 guide.

The GraphQL endpoint

The Wiz GraphQL API has a single endpoint https://api.<region>.app.wiz.io/graphql , where
<region> is the AWS region your tenant resides, e.g., us1 , us2 , eu1 or eu2 . The
endpoint remains constant no matter what operation you perform.

To get your GraphQL endpoint:

1. At the top right of your Wiz portal, click the user icon > User settings (direct link).
2. At the left side, click Tenant (direct link).
3. Copy your API Endpoint URL.

Communicating with GraphQL

Wiz uses GraphQL APIs, which are similar to REST APIs. The building blocks you need to know
are queries and mutations.

• Queries in GraphQL means to fetch data, similar to GET calls in REST.

• Mutations means to modify data, similar to state-changing methods in REST like DELETE,
POST, PUT, and PATCH.

 Read the GraphQL basics guide to learn more.

GraphQL operations consist of structured multiline JSON. We recommend experimenting with

the API Explorer when building new GraphQL API calls. You can also use cURL or any other
HTTP-speaking library in your preferred programming language.
In REST, HTTP verbs determine the operation performed. In GraphQL, you'll provide a JSON-
encoded body whether you're performing a query or a mutation, so the HTTP verb is POST .

To query GraphQL using cURL, make a POST request with a JSON payload. The payload
must contain a string called query :

Shell

# Replace <YOUR_API_ENDPOINT_HERE> with your own Wiz API endpoint, e.g. https://api.us1.app.wiz.io/graphql
curl <YOUR_API_ENDPOINT_HERE> \
-H "Authorization: bearer YOUR_TOKEN_HERE" \
-H 'content-type: application/json' \
-X POST \
-d '{"query": "query { issues { totalCount }}"}'

 The string value of "query" must escape newline characters or the schema will
not parse it correctly. For the POST body, use outer double quotes and escaped
inner double quotes.

Wiz API rate limits and timeouts

 These limits do not apply to service accounts of type Sensor or Complete K8s
Deployment. In these cases, a single service account can be used to cover your
entire production environment

To avoid excessive impact on its backend, Wiz implements the following rate limits and
timeout:

Limit Description

This limit is applied for each user and service account, so 5 service
10 API calls
accounts on the same tenant could each make 10 calls per second, or 50
per second
calls per second total

This limit is applied across all users and service accounts on a tenant, so
100 API
10 service accounts could each make 10 calls per second or 20 service
calls per
accounts could make 5 calls per second, but 11 service accounts
second
attempting 10 calls per second would trigger throttling

5 minute
API calls have a timeout of 5 minutes per query.
timeout

If you have an environment with large concurrency requirements for remote access to Wiz
(e.g. CI/CD pipelines with dozens of Wiz CLI scans per second, which is quite rare), then:
 • Consider using different service accounts for each, or
• Embed a retry on throttle error mechanism in your scripts

In case you are encountering a timeout, consider optimizing the query by following our
optimizing queries guide.

Examples

Fully annotated script Recipe

We recommend you start by reviewing a fully annotated script Recipe:

Fetching Issues, Controls, and Frameworks

� Open Recipe 

Pagination
Each API query has a maximum output of 500 or 1,000 records. If you have more (and aren't
using quick search, which returns only 50 results), you can then paginate through up to 10,000
records. The hasNextPage attribute indicates whether there are more pages to load, and you
receive the next page endCursor as long as there is a next page. To receive these attributes
in the response, you must explicitly tell the API that you want the pageInfo response node
to populate in the responses.

 max pagination value

As of August 1st, 2023, pagination for the query graphSearch is limited to 10,000
total results. Custom scripts created before then that paginated through tens or
hundreds of thousands of results should be updated to use more selective queries
and repeated calls, each of which returns fewer than 10,000 results.

To paginate your results:

1. Run a query to get results. Make sure pageInfo is in the request.

2. If hasNextPage response parameter exists in pageInfo , then:
a. Run the query again starting from endCursor .
b. Save new pageInfo .
c. Repeat.

Make sure the API query includes both the pageInfo parameter and a first variable
(where 0 < first ≤ 10,000) that determines the batch size of each iteration.

Here is an example in Python:

 Python

result = query_wiz_api(token, query, variables)

print(json.dumps(result))

# Change according to your result structure:

pageInfo = result['issues']['pageInfo']

# Check if there are additional results

while (pageInfo['hasNextPage']):
# fetch next page
variables['after'] = pageInfo['endCursor']
result = query_wiz_api(query, variables)
print(result)
pageInfo = result['issues']['pageInfo']

A query that fetches open Issues

This query uses the issues query field to fetch the 20 highest severity Issues that have open
or in-progress status and returns each Issue's id, Severity, Related Entity details, and the
originating Control Name.

JSON

query {
issues(
first: 20
filterBy: { status: [OPEN, IN_PROGRESS] }
orderBy: { direction: DESC, field: SEVERITY }
) {
nodes {
id
severity
entity {
id
name
type
}
control {
name
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
Adding a connector mutation
Programmatically adding a connector using the API is useful when you need to connect
several cloud accounts.

Request

mutation ExampleAddConnector {
createConnector(
input: {
name: "My new connector",
type: "aws",
authParams: {
customerRoleARN: "arn:aws:iam::123456:role/WizAccessSomeRoleName"
},
extraConfig: {}
}
) {
connector {
id
name
}
}
}

Response

{
"data": {
"createConnector": {
"connector": {
"id": "89db2cae-d047-43e0-b2fd-a7633b13283c",
"name": "My new connector"
}
}
}
}

Additional resources
There is a lot more you can do when forming GraphQL calls. Here are some places to look
next:

• Our Wizards have written and annotated numerous example scripts that you are free to
use and modify. Explore the Recipes.
• GraphQL basics guide
• Migrating from REST to GraphQL (Github docs)
• Wiz API Explorer & Docs
 Updated 10 days ago

 Introduction to Wiz API APIs and Required Permission


Scopes

Did this page help you?  Yes  No