Use the API

Learn how to use the StackRox Kubernetes Security Platform APIs.

4 minute read

The StackRox Kubernetes Security Platform API reference documentation provides detailed information for all endpoints. You can view the detailed API reference documentation from the StackRox portal. This section introduces basic concepts about the API, authentication, and examples to get you started with the StackRox Kubernetes Security Platform API.

View the API reference documentation

You can view the API reference from within the StackRox Kubernetes Security Platform. To do this:

  • For the StackRox Kubernetes Security Platform version 3.0.44 or older:

    1. On the StackRox portal, navigate to Help > API reference.
  • For the StackRox Kubernetes Security Platform version 3.0.45 or newer:

    1. Select API reference from the left-hand navigation menu.

The API reference documentation provides an example response for each API endpoint. The example response includes all the attributes that endpoint returns.

Schema

All API access is over HTTPS, and all data that you send must be in JSON format. All API responses are in JSON format.

Blank fields

All responses include blank fields as null instead of omitting them.

Timestamps

All timestamps are in Coordinated Universal Time (UTC) and are in this format:

Copy
YYYY-MM-DDTHH:MM:SSZ

Summary representations

When you request a list of resources, the API provides the list of resources including a subset of the attributes for each resource. To get all attributes for a specific resource, request detailed representations.

The StackRox Kubernetes Security Platform APIs don’t return passwords, secret tokens, or other authentication values. These fields are always omitted from the responses.

For example, when you request a list of deployments.

Copy
curl -H "Authorization: Bearer <auth-token>" https://<stackrox-portal-address>/v1/deployments

The response includes some attributes for every deployment, which are id, name, cluster, clusterId, namespace, updatedAt, and priority. It doesn’t include fields like the details of the containers and images that are running in each deployment.

Copy
{
    "deployments": [
        {
            "id": "686b2e86-43c2-11d7-3363-42010a8000e2",
            "name": "jump-host",
            "cluster": "development",
            "clusterId": "d8687924-ad37-56c1-6b01-d96a9501c35f",
            "namespace": "database",
            "updatedAt": "2019-04-17T01:44:58Z",
            "priority": "1"
        },
        {
            "id": "67d306b8-26b2-118e-9515-42010a8000e2",
            "name": "call-processor",
            "cluster": "production",
            "clusterId": "d8687924-6b01-47d1-ad37-d96a9501e35f",
            "namespace": "records",
            "updatedAt": "2019-04-17T01:44:57Z",
            "priority": "2"
        }
    ]
}

Detailed representations

When you request a single resource, the response includes all attributes for that resource, including those attributes that you don’t get in a summary representation.

For example, when you request a specific deployment.

Copy
curl -H "Authorization: Bearer <auth-token>" https://<stackrox-portal-address>/v1/deployments/686b2e86-43c2-11d7-3363-42010a8000e2

The response includes information about all resources.

The amount of detail you receive in responses depends upon the authorization role you specify when you generate an access token.

Authentication

Our APIs use the HTTP authentication scheme and involve security tokens called bearer tokens. You must generate this token and send this token in the Authorization header for all API requests.

  • Make all request over HTTPS.
  • All API requests without authentication will fail.

Generate an access token

To generate an access token:

  1. Navigate to the StackRox portal.

  2. Go to Platform Configuration > Integrations.

  3. Scroll down to the Authentication Tokens category, and select API Token.

  4. Select Generate Token.

  5. Enter a name for the token and select the role.

  6. Select Generate.

    Copy the generated token and securely store it. You won’t be able to view it again.

  7. After you have generated the authentication token, send it in a request header. For example:

    Copy
    curl -i -H "Authorization: Bearer <auth-token>" https://<stackrox-portal-address>/v1/ping

Find token expiry time

To find out when your token expires, use the v1/auth/status endpoint.

Copy
curl -H "Authorization: Bearer <auth-token>" https://<stackrox-portal-address>/v1/auth/status

{
    "userId": "auth-token:ae9dc5a0-fe22-4f4f-63c5-9ebc67e0b527",
    "expires": "2020-04-14T00:30:23Z",
    "refreshUrl": ""
}

The expires field in the response shows the token expiry time.

Get token permissions

Use the v1/mypermissions endpoint to identify read and write permissions the token allows, for each resource.

Copy
curl -H "Authorization: Bearer <auth-token>" https://<stackrox-portal-address>/v1/mypermissions

{
    "name": "",
    "globalAccess": "READ_ACCESS",
    "resourceToAccess": {
        "APIToken": "READ_ACCESS",
        "Alert": "READ_ACCESS",
        "AuthProvider": "READ_ACCESS",
        "Cluster": "READ_ACCESS",
        "Compliance": "READ_ACCESS",
        "ComplianceRunSchedule": "READ_ACCESS",
        "ComplianceRuns": "READ_ACCESS",
        "DebugLogs": "READ_ACCESS",
        "DebugMetrics": "READ_ACCESS",
        "Deployment": "READ_ACCESS",
        "Detection": "READ_ACCESS",
        "Group": "READ_ACCESS",
        "Image": "READ_ACCESS",
        "ImageIntegration": "READ_ACCESS",
        "ImbuedLogs": "READ_ACCESS",
        "Indicator": "READ_ACCESS",
        "K8sRole": "READ_ACCESS",
        "K8sRoleBinding": "READ_ACCESS",
        "Licenses": "READ_ACCESS",
        "Namespace": "READ_ACCESS",
        "NetworkGraph": "READ_ACCESS",
        "NetworkPolicy": "READ_ACCESS",
        "Node": "READ_ACCESS",
        "Notifier": "READ_ACCESS",
        "Policy": "READ_ACCESS",
        "Role": "READ_ACCESS",
        "Secret": "READ_ACCESS",
        "ServiceAccount": "READ_ACCESS",
        "ServiceIdentity": "READ_ACCESS",
        "User": "READ_ACCESS"
    }
}

The globalAccess field in the response shows the default permission that applies to all resources. The resourceToAccess object shows permissions for every resource in the response and it overrides the default globalAccess permission.

HTTP verbs

Our APIs support the following HTTP verbs for interacting with the resources:

VerbDescription
GETUsed for retrieving resources.
POSTUsed for creating resources.
PATCHUsed for updating resources with partial JSON data. Some endpoints allow this method, such as resolving alerts or enabling or disabling policies. To change other fields, use PUT.
PUTUsed for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETEUsed for deleting resources.

When you create a new object by using a POST request, the response body includes the object ID and all fields assigned to this object. You can refer to this object using the object ID.

HTTP response status codes

Our APIs use the HTTP response status codes to show the success or failure of an API request. In general, codes in the 2xx range suggest success and codes in the 4xx range suggest an error.

StatusDescription
200Successful request.
401Unauthenticated request. It means that the client must authenticate itself to get the requested response.
403The client doesn’t have access rights to the requested content.
404The server can’t find the requested resource.
500The server encountered an error.

Parameters

Our APIs use 4 main categories of parameters for each endpoint: path, query, request body and response body. Our API documentation includes a list of available parameters for each request.

Beginning from the StackRox Kubernetes Security Platform version 3.0.42, you can now request pretty-printed JSON responses for all v1 API endpoints by adding the ?pretty path parameter in your requests. For example:

Copy
curl -H "Authorization: Bearer <auth-token>" https://<stackrox-portal-address>/v1/auth/status?pretty

Path parameters

Some of our API URLs include resource names and unique identifiers to help you structure your requests. You must replace them with real values when making a request. For example:

Copy
curl -H "Authorization: Bearer <auth-token>" https://<stackrox-portal-address>/v1/authProviders/{id}

In this request, the URL includes 1 path parameter, id. You must replace it with a real value when you make a request. After you replace this value with actual data, your final request looks like this:

Copy
curl -H "Authorization: Bearer <auth-token>" https://<stackrox-portal-address>/v1/authProviders/aff6e862-5344-23a4-8454-1a5ac1e6fa77

Query string parameters

Some of our APIs use query string parameters for sorting, filtering, and pagination. The format for query string parameters is the full resource URL followed by a question mark ?, the query string query= and your search query foo:

https://<stackrox-portal-address>/v1/<endpoint>?query=foo

You must always URL-encode your search query.

For example, to get all deployments where:

  • the namespace name is backend OR stackrox AND
  • the cluster name is production AND
  • the deployment matching the pattern is .*a.*.

The query is Namespace:backend,frontend+Cluster:production,+Deployment:r/.*a.*.

Copy
curl -H "Authorization: Bearer <auth-token>" https://<stackrox-portal-address>/v1/deployments?query=Namespace%3Abackend%2Cfrontend%2BCluster%3Aproduction%2C%2BDeployment%3Ar%2F.%2Aa.%2A

The query parameter in this request:

Copy
Namespace%3Abackend%2Cfrontend%2BCluster%3Aproduction%2C%2BDeployment%3Ar%2F.%2Aa.%2A

is the URL-encoded value of the query.

Request body parameters

For some of our APIs you must include a request body in JSON format. The following example shows you how to generate an API token for a specific role.

Copy

curl -X POST -H "Authorization: Bearer <auth-token>" -d "{
 \"name\": \"API token\",
 \"role\": \"Analyst\",
}" https://<stackrox-portal-address>/v1/apitokens/generate

Response body parameters

Every API call response includes headers and an optional JSON-formatted body. The documentation includes all response body parameters. The following example shows the JSON-formatted response to expect from a POST request to GetAuthStatus service:

Copy
{
    "userId": "auth-token:ae9dc5a0-43ef-2f2f-65c3-9ebc67e0b527",
    "expires": "2020-04-14T00:30:23Z",
    "refreshUrl": ""
}

Pagination

Some APIs have pagination parameters by using which you can limit the number of results in the response. API documentation lists whether an endpoint supports pagination. Use the pagination.limit and pagination.offset parameters to request data in batches rather than all at once.

  • Use the pagination.limit parameter to specify the number of items you need in the response.
  • Use the pagination.offset parameter to specify the item number for the first item in the response.
  • If you specify pagination.limit=n and don’t specify pagination.offset or specify it as pagination.offset=0 the response includes the first n items.
  1. Pagination isn’t available on some APIs (ComplianceService, ListPolicies, and RbacService) even though API documentation lists these parameters.
  2. For APIs that support pagination, it’s always available as a URL parameter.

Consider a sample response {a, b, c, d, e, f, g, h, i, j }:

  • To get the first 4 elements (a, b, c, d), specify pagination.limit=4.
  • To get the next 4 elements (e, f, g, h), specify pagination.limit=4 and pagination.offset=4.
  • To get the remaining 2 elements (i, j), specify pagination.limit=4 and pagination.offset=8.

For example, to get the first 5 alerts, send the request:

Copy
curl -H "Authorization: Bearer <auth-token>" https://<stackrox-portal-address>/v1/alerts?pagination.limit=5

To get the next 5 alerts, add the parameter pagination.offset=5 in your original query.

Copy
curl -H "Authorization: Bearer <auth-token>" 'https://<stackrox-portal-address>/v1/alerts?pagination.limit=5&pagination.offset=5'

Questions?

We're happy to help! Reach out to us to discuss questions, issues, or feature requests.

© 2021 StackRox Inc. All rights reserved.