# Public API

> Settings > Integrations > Public API: Swagger and base URL, enable API, rate limits, token expiry, and which roles may use the API for CI/CD.

Source: https://totalshiftleft.ai/help-center/product-documentation/public-api

## Overview

This guide walks you through the **Public API Settings** screen in Shift Left Studio exactly as it appears, so you can expose (or disable) the Public API, tune rate limits and token expiry, and restrict access by role. The **Public API** is the REST interface CI/CD pipelines use to trigger test packs and read results (log in, run a pack, poll status).

Explore the capability at [api keys](/features/collaboration-security/api-keys). Where to find everything: [Administration Settings](/help-center/product-documentation/administration-settings).

**Availability:** Professional and Enterprise. The unauthenticated `/api/v1/health` check is always available regardless of edition.

## Before you begin

- You must be an administrator. Navigate to **Settings → Integrations → Public API**.
- The subtitle reads *"Configure external API access for CI/CD integration and automation."*
- Two buttons sit at the top of the screen: **Reset to Defaults** (restores default values after a confirmation) and **Save Settings** (persists your changes — nothing is saved until you click it).

## Step 1 — Copy the documentation URLs

At the top, the **API Documentation** banner gives two copyable links (host and port depend on your deployment):

| Item | What it is |
|------|-----------|
| **Swagger UI** | Interactive docs at `<host>/api-docs`. Click the copy icon to grab it; point internal consumers here. |
| **Base URL** | REST root at `<host>/api/v1`. Click the copy icon to use it in pipelines. |

Copying either shows **"Copied to clipboard!"**

## Step 2 — General settings

In the **General Settings** card:

| Field | What it does |
|-------|--------------|
| **Enable Public API** | Master checkbox for programmatic access. Uncheck to disable the API (except `/api/v1/health`). |
| **Current API Version** | Read-only, e.g. **v1**. The helper text notes *"API version is read-only."* |

## Step 3 — Rate limiting

In the **Rate Limiting** card:

| Field | What it does |
|-------|--------------|
| **Enable rate limiting to protect API from abuse** | Checkbox. When on, the two limits below appear and apply. |
| **Max Requests Per Minute** | Short-burst cap (1–1000), default **100**. |
| **Max Requests Per Hour** | Sustained cap (1–10000), default **1000**. |

Tighten these in production; raise them only with evidence of legitimate throughput needs.

## Step 4 — Authentication

In the **Authentication** card:

| Field | What it does |
|-------|--------------|
| **Public API Token Expiry** | Dropdown for how long issued JWTs stay valid: **1 Hour**, **6 Hours**, **12 Hours**, **1 Day**, **7 Days (Recommended)**, **30 Days**, **90 Days**. Shorter expiry reduces risk if a token leaks. |
| **Allowed Roles** | Checkboxes for which roles may obtain/use API access: **Administrator**, **Tester**, **Contributor**, **Reader**. Enable only the roles that need automation. |

A login attempt from a role that isn't in **Allowed Roles** is rejected with **"Your role (…) is not allowed to access the Public API"** (HTTP 403).

## Step 5 — CORS

In the **CORS (Cross-Origin Resource Sharing)** card (with a **Security Warning** that allowing all origins is convenient but less secure):

| Field | What it does |
|-------|--------------|
| **Enable CORS to allow cross-origin API requests** | Checkbox. When on, the origins field appears. |
| **Allowed Origins** | Comma-separated origins, e.g. `https://example.com, https://another.com`. Use `*` for all origins — avoid this in production; allow-list trusted domains instead. |

## Step 6 — Save

Click **Save Settings** (it shows **Saving...** while working). On success you'll see **"Public API settings saved successfully."** To restore defaults, click **Reset to Defaults**, then confirm in the **Reset Public API Settings** dialog (this cannot be undone).

## The CI/CD login → run → poll flow

The **Available Endpoints** section lists all 8 endpoints. A typical pipeline uses them in this order:

1. **`POST /api/v1/login`** — authenticate with email + password to receive a JWT. Send it as `Authorization: Bearer <token>` on every later call. (Login events are audited as `cicd_login`.)
2. **`GET /api/v1/test-packs`** — list available packs (optionally filter by `projectName` or `environment`) to find the `packId`.
3. **`POST /api/v1/test-packs/{packId}/run`** — trigger execution. Returns an `executionId` and `status: RUNNING`; the run is asynchronous. (Audited as `cicd_execute`.)
4. **`GET /api/v1/test-packs/{packId}/status`** — poll for completion; returns the pack status and a pass/fail summary with `successRate`.
5. **`GET /api/v1/test-packs/{packId}/results`** — fetch per-test-case results (status, duration, error).

Other endpoints: **`GET /api/v1/test-packs/{packId}`** (pack details), **`GET /api/v1/test-packs/{packId}/history`** (recent executions), and **`GET /api/v1/health`** (always available, no auth).

## Using API keys instead of username/password

Rather than logging in with a user's email and password, you can issue a scoped, rotatable **API key** and send it on API requests. Keys are safer for automation because they carry only the scopes you grant, can expire, and can be rotated or revoked without touching a user account. See [API keys](/help-center/product-documentation/api-keys).

## Best practices

- Keep the API **disabled** until you have an integration owner and monitoring.
- Store tokens and API keys in a [secret manager](/help-center/product-documentation/secret-managers), never in repos.
- Revoke unused tokens/keys and review **Allowed Roles** after org changes.

## Related articles

- [API keys](/help-center/product-documentation/api-keys)
- [Role Permissions](/help-center/product-documentation/role-permissions)
- [Audit Logs](/help-center/product-documentation/audit-logs)
- [Configuration fundamentals](/help-center/configuration/environment-variables)