Skip to main content

CI Sense API

This document forms the Getting Started Guide for the API that Code Intelligence provides to manage basic entities of CI Sense like users, accounts, organizations and projects.

It provides an overview and includes low-level example usage of the API.

API version overview​

The new HTTP API is available under the /v3 prefix path of our CI Sense backend.

Make sure you are using CI Sense release version 3.16.0 or greater.

Swagger​

Documentation of this API can be found via Swagger UI hosted in CI Sense at https://<server address>/v3/index.html. For example in our SaaS environment that would be https://app.code-intelligence.com/v3/index.html. Alternatively the Swagger JSON is availabe at https://app.code-intelligence.com/v3/swagger.json.

Concepts​

The HTTP API is RESTful and uses globally unique identifiers for resources (aliased as nid).

Users, accounts and organizations​

The API assumes certain knowledge of CI Sense domain models, specifically:

  • User: The actual user logging in (representing a person).
  • Account: A tenant in CI Sense (similar to Github Organizations). All organizations and projects belong to one account. Users may be members of more than one account. CI Sense resource limits (e.g. total fuzzing minutes) are managed at the account level.
  • Organization: A group of one or more projects. User permissions and access are managed at the organization level.
  • Project: The collection of actual fuzzing runs and findings for a specific software project.

There are two kinds of accounts: personal and group. Each user in CI Sense has a personal account automatically created (to allow limiting overall resource usage for private projects). Group accounts allow modeling multiple tenants (with independent resource limits); if this is not necessary, one group account could be used for all organizations and projects.

Authentication​

Access Tokens​

Requests to our API are authenticated with access tokens that can be generated in our UI. When logged in into CI Sense, open the user's settings and select the Tokens tab, where you can generate new tokens.

Add your access token via the Authorization header to every request:

"Authorization: Bearer $YOUR_TOKEN"

Server Root​

Certain routes of the API require escalated Server Root privileges. For example, listing all global accounts and users on the server require the Server Root role.

The Server Root role is managed automatically via the OIDC integration. The users will be granted and revoked Server Root privileges during OAuth login.

GitHub Integration​

Enabling Server Root privileges with GitHub integration depends on GitHub Teams:

  • A specific team must be created in GitHub and configured in CI Sense (CIFUZZ_GITHUB_SERVER_ROOT_ORGANIZATION_SLUG and CIFUZZ_GITHUB_SERVER_ROOT_TEAM_SLUG).
  • Their presence/absence in this team will grant/revoke them Server Root privileges. Note that the user has to login for changes to take effect.

Troubleshooting​

If you run into troubles using the API, this section might be helpful.

The Content Type header​

When passing a request body with JSON (e.g. with POST/PUT requests), make sure to add the Content Type header:

Content-Type: application/json

Otherwise the API will respond with 400 Bad Request errors.

Example use cases​

This section provides example usages of the API.

The examples are written with bash scripting in mind and require curl.

Setup​

#!/usr/bin/env bash

set -e

# Set this to an access token you created (see above)
ACCESS_TOKEN='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

# Set this to the host (hostname and optional port)
CI_BACKEND_HOST='127.0.0.1:8080'

function curl_ci_backend()
{
  ROUTE="$1"
  shift

  URL="http://$CI_BACKEND_HOST/v3/$ROUTE"

  echo -e "Requesting $URL\n"

  curl "$URL" \
    --fail-with-body \
    --include \
    --no-progress-meter \
    -H 'Accept: application/json' \
    -H 'Accept-Language: en-US,en;q=0.9' \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H 'Content-Type: application/json' \
    --compressed \
    "$@"

  echo -e "\n"
}

User management​

Listing users​

As server root (see above), you can obtain a list of all users on the server like this:

curl_ci_backend 'server/users'

This will respond with a list of all users including their details like name, OIDC login and user-nid (globally identifier).

Creating users​

Users are not created explicitly, but from an external identity provider on OIDC login.

Deleting users​

A user can be deleted via their user-nid like so:

user_nid='usr-abcd1234efgh'
curl_ci_backend "server/users/$user_nid" -X DELETE

Note that users that are the last administrator of a group account can not be deleted, since group accounts must always have at least one administrator.

Deleting users will also automatically delete all of the private projects.

Account management​

Listing accounts​

Every user always has their own unique personal account. The endpoint to list accounts on the server only returns group accounts.

curl_ci_backend 'server/accounts'

Creating accounts​

While personal accounts are created (and deleted) along with their corresponding users, group accounts require more attention.

Group accounts are a new feature that is not yet exposed on the UI. Therefore, at the moment group accounts are created automatically when a user creates an organization.

Note that as of now, there is no way to explicitly create group accounts via the API. Please contact Customer Success if there are issues with the automatically created group accounts.

Deleting accounts​

Personal accounts are deleted automatically once their user is deleted. Group accounts are meant for collaboration and exist alongside specific user membership. This is why they have to be deleted explicitly.

Admins of the account or users with server root privileges can delete a group account like this:

account_nid='acc-abcd1234efgh'
curl_ci_backend "accounts/$account_nid" -X DELETE

As server root, you may want to use this to delete undesired group accounts that were created by other users on the system.

Note that when deleting group accounts, every organization and project that belongs to it will be deleted, too!

Organization management​

Listing organizations​

To list every organization of a specific group account:

account_nid='acc-abcd1234efgh'
curl_ci_backend "accounts/$account_nid/organizations"

Getting organizations​

Obtain a specific organization including its members:

organization_nid='org-abcd1234efgh'
curl_ci_backend "organizations/$organization_nid"

Creating organizations​

Create an organization within a specific account via the API. The payload requires a (globally unique) organization name:

account_nid='acc-abcd1234efgh'
curl_ci_backend "accounts/$account_nid/organizations" -X POST -d '{"organization_name": "Super org"}'

Deleting organizations​

To delete a specific organization:

organization_nid='org-abcd1234efgh'
curl_ci_backend "organizations/$organization_nid" -X DELETE

Organization membership​

Users can be added or removed from an organization, or have their roles changed:

# Add or update membership
organization_nid='org-abcd1234efgh'
user_nid='usr-abcd1234efgh'
curl_ci_backend "organizations/$organization_nid/members/$user_nid" -X PUT -d '{"organization_role": "member"}'

# Remove membership
organization_nid='org-abcd1234efgh'
user_nid='usr-abcd1234efgh'
curl_ci_backend "organizations/$organization_nid/members/$user_nid" -X DELETE

Available roles are member and administrator.

Project management​

Listing projects​

You can list projects for an organization like this:

organization_nid='org-abcd1234efgh'
curl_ci_backend "organizations/$organization_nid/projects"

Note that some details can only be retrieved when getting a single project, not a list.

As server root, you can obtain a list of all projects on the server like this:

curl_ci_backend 'server/projects'

Creating projects​

You can create group projects within an organization as follows:

organization_nid='org-abcd1234efgh'
project_name='my-project-12378'
project_contact_user_nid='usr-abcd1234efgh'
curl_ci_backend "organizations/$organization_nid/projects" -X POST -d "{"\""project_name"\"": "\""$project_name"\"", "\""project_contact"\"": {"\""user_nid"\"": "\""$project_contact_user_nid"\""}}"

Projects creation requires at least a project name and a project contact. The project contact is identified via their user nid and must be member of the project's organization.

Getting projects​

Obtain a specific project including its details via their nid:

project_nid='prj-abcd1234efgh'
curl_ci_backend "projects/$project_nid"

Updating projects​

A project can be updated as well, e.g. to change their Git URL:

project_nid='prj-abcd1234efgh'
project_git_url='https://example.com/my-project.git'
curl_ci_backend "projects/$project_nid" -X POST -d "{"\""project_git_url"\"": "\""$project_git_url"\""}"

Deleting projects​

A project can be deleted like so:

project_nid='prj-abcd1234efgh'
curl_ci_backend "projects/$project_nid" -X DELETE

Other entities​

Managing further entities like findings and runs etc. is currently not officially supported via the CI Sense API.