Welcom to Seemplicity's GraphQL API documentation. If you're interested in using the Seemplicity API, contact Customer Services to have the API enabled for your company. You can find further relevant topics in the Seemplicity Knowledge Base here.

Learn how to query and pull data into your workspace — quickly and efficiently.

Use this guide to get started with the Seemplicity API quickly. This guide will show you how to:

1. Generate a Seemplicity API token in the production environment.
2. Make your first API call using the production endpoint.

For our Seemplicity GraphQL API Reference, see our documentation here.

Get started in the production environment

This guide uses cURL.

Prerequisites

Confirm with Customer Services that Seemplicity has enabled the API for your company and provides access to the Authentication - API Token settings.

The following procedure explains how to acquire the required parameters for your company:

• <API_TOKEN>
• <API_URL>

Generate a Bearer Token and start using the Seemplicity API

To access the Seemplicity API:

1. From Seemplicity's top menu ar, go to Settings > Authentication - API Tokens.
2. Select +Add API Token. The API Token dialog displays.
3. Enter a descriptive Name and select Create.
4. Copy the generated token and save it for future use. When finished, select Close.
5. Next, generate a JWT from the token in step 4 by running the script in your preferred coding platform. See the Note and the example scripts in Bash and Python, below.
6. Copy the JWT. It will be valid for a limited period of time. This is the Bearer <JWT> token.

Example Scripts (in Bash and Python)

 
#!/bin/bash
REGION="eu-central-1"

token=$(echo "$1" | base64 -d | curl -s -X POST \
-d @- \
-H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
-H 'Content-Type: application/x-amz-json-1.1' \
"https://cognito-idp."$REGION".amazonaws.com/" | jq -r ".AuthenticationResult.AccessToken")

echo $token

 
import requests
import base64
import json

REGION = 'eu-central-1'


def get_token(api_key: str) -> str:
    cognito_data = base64.b64decode(api_key)
    cognito_url = f'https://cognito-idp.{REGION}.amazonaws.com'
    cognito_headers = {'X-Amz-Target': 'AWSCognitoIdentityProviderService.InitiateAuth',
                       'Content-Type': 'application/x-amz-json-1.1'}
    cognito_response = requests.post(cognito_url, headers=cognito_headers,      data=cognito_data)
    return json.loads(cognito_response.content)['AuthenticationResult']['AccessToken']

Make your API call: example in cURL

 
curl --location 'https://api.seemplicity.io/api/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <JWT>' \
--data '{"query":"query get_finding_by_id($id: ID!) {\n  finding(id: $id) {\n    id\n    id_int\n    finding_id\n    last_reported_time\n    cloud_provider\n    original_status\n    discovered_time\n    cloud_account\n    package_name\n    datasource {\n      friendly_name\n    }\n    main_resource {\n      resource_name\n    }\n    title\n    finding_score {\n      score\n      severity\n      original_score\n    }\n    age\n    description\n  }\n}","variables":{"id":"RmluZGluZzoxODAxNTA="}}'

 
{
    "data": {
        "finding": {
            "id": "RmluZGluZzoxODAxNTA=",
          "id_int": 180150,
            "finding_id": "1-1-findings.id IN (902, 905) and (1 is not null)",
            "last_reported_time": "2021-04-07T14:52:29+00:00",
            "cloud_provider": "github",
            "original_status": "",
            "discovered_time": "2022-02-19T06:58:31+00:00",
            "cloud_account": "github:mobile-app",
            "package_name": null,
            "datasource": {
                "friendly_name": "GHB"
            },
            "main_resource": {
                "resource_name": "mobile-app"
            },
            "title": "Code Injection in js-yaml - Multiple Vulnerabilities",
            "finding_score": {
                "score": 10.0,
                "severity": 3,
                "original_score": null
            },
            "age": 709,
            "description": "Versions of `js-yaml` prior to 3.13.1 are vulnerable to Code Injection. The `load()` function may execute arbitrary code injected through a malicious YAML file. Objects that have `toString` as key, JavaScript code as value and are used as explicit mapping keys allow attackers to execute the supplied code through the `load()` function. The `safeLoad()` function is unaffected.\n\nAn example payload is \n`{{ toString: !<tag:yaml.org,2002:js/function> 'function (){{return Date.now()}}' }} : 1` \nwhich returns the object \n{{\n  \"1553107949161\": 1\n}}\n\n\n## Recommendation\n\nUpgrade to version 3.13.1."
        }
    }
}

The Query type in GraphQL represents the entry point for retrieving data from the API. It defines the available read-only operations (queries) that clients can execute to fetch data.

Customer-facing GraphQL mutations for managing findings, rules, and resources. These mutations require appropriate permissions and are scoped to the customer's organization.

The Subscription type in GraphQL enables real-time communication between clients and the server. It defines a set of events or data streams that clients can subscribe to and receive updates whenever the subscribed events occur.

Objects in GraphQL represent complex data structures. They define the fields and their types that can be queried in a GraphQL API. Objects can have nested fields and relationships with other objects.

Scalars: Scalars in GraphQL represent primitive data types, such as String, Int, Boolean, Float, etc. They are used to define the types of individual fields in the GraphQL schema.

Directives in GraphQL provide a way to control the execution behavior of queries and mutations. They allow you to modify the result, change the execution order, skip or include fields conditionally, and apply custom logic to the resolution process.

Enums in GraphQL define a set of possible values for a field. They represent a discrete set of options or states that a field can have. Enums help ensure type safety and provide a clear list of valid values for a field.

Unions in GraphQL allow you to combine multiple object types into a single type. They represent a result that can be one of several object types. Unions are useful when a field can return different types of objects, and you want to specify all the possible types in the schema.