Authenticate with the v2 API

Send requests to your tenant host, https://<tenant>.katalon.io, over HTTPS.
Authenticate with a Katalon API key. Use HTTP Basic with an empty username
and the API key as the password:
Authorization: Basic <base64(:API_KEY)>.

An API key uses its owner's access; it does not grant additional permissions.
Keep both the key and its Base64 value secret. Encoding is not encryption.

1. Create an API key

Sign in to Katalon True Platform.
Click your profile in the top-right corner and select User Settings.
Select the Katalon API Key tab.
Click Create API Key. Enter a key name, choose an expiration period, and
optionally add a description.
Click Create, then copy the key.

See Katalon API Key in Katalon True Platform
for details.

2. Find your project ID

Every v2 request needs a numeric project ID in the x-project-id header, even
a request that lists projects.

Open a project you can access in the True Platform UI.
Copy the numeric project ID from the project URL in your browser.
To find other projects, call
List projects
with that ID as x-project-id. Use each returned project id as
x-project-id for that project.

A project ID is not a repository ID. See Know which ID is which.

3. Send project context

x-project-id is required on every request.
x-account-id selects account context and takes an account UUID, not a
numeric account ID. Storage and Admin (AUT, environment and custom-field)
requests require it. Other requests accept it as an option.
x-organization-id is optional numeric organization context. If supplied, the
account and organization must be consistent with the project.

Context headers do not grant membership or permission. Check each operation's
permission requirements and use the correct resource ID type.

4. Pass credentials through curl's standard input

Set KATALON_API_HOST, KATALON_API_KEY, and KATALON_PROJECT_ID from your
environment or secret store. Use the Bash helper below to keep the key out of
curl's command-line arguments. Do not enable shell tracing (set -x). If the key
contains " or \, escape those characters as \" and \\ for curl's
configuration format.

katalon_request() {
  : "${KATALON_API_KEY:?Missing API key}"
  printf 'user = ":%s"\n' "${KATALON_API_KEY}" |
  curl --config - --silent --show-error --fail-with-body \
    --header "x-project-id: ${KATALON_PROJECT_ID:?Missing project ID}" \
    "$@"
}

katalon_request "${KATALON_API_HOST:?Missing tenant host}/v2/schedules"

To select account or organization context, add the corresponding header to a
request. Keep x-project-id in the helper on every call. Do not send your API
key to a separate signed upload or download destination returned by an operation.

Know which ID is which

Term	ID to use	Notes
Project	`x-project-id` header	The numeric project ID from step 2.
Repository	`testProjectId` in Test Management payloads; `id` in repository search	A script or test repository inside a project. It is not the project ID.
Schedule	Schedule `id` in `GET /v2/schedules`	A saved schedule. Also called a run configuration.
Scheduler	`schedulers[].id` in a schedule	When a schedule runs. Use it with `startTime` to run that occurrence now.
Run configuration entry	`runConfigurationEntries[]` in a schedule or a test-run request	The tests, repository (`testProjectId`), profile and environments to run.
Test run	`id` returned when you start a run; `executionId` or `{id}` in `/v2/schedules/test-runs` paths	One run of the tests. The guides save it as `TEST_RUN_ID`.
Test result	`executionTestResultId` in a run's result list	One test case's result in a test run.
Manual execution	`id` or `executionId` in `GET /v2/manual-test/executions`	Used only in `/v2/manual-test/executions/...` paths.
`externalExecutionId`	Field on a manual execution	The separate TestOps run ID. Use it as `sourceId` for run-level manual activity. Do not use it in manual-execution paths.
Requirement	Requirement `id`	The True Platform requirement ID. Use it in requirement link requests.
Requirement `sourceId`	Field on a requirement	The ALM issue key, such as `DEMO-42`. Use it as the issue ID in ALM requests.
Requirement `externalIssueId`	Field on a requirement	Not a substitute for the issue key in ALM requests.

Understand authentication errors

Status	What to check
`401`	The API key is missing, invalid, or no longer usable. Confirm HTTP Basic uses an empty username and the key as the password.
`403`	The caller lacks access or a required permission, or the supplied context or resource ID is not accepted.
`400`	A required header or parameter is missing, an ID has the wrong form, or a request or filter is invalid. Check the operation's input contract.

A missing x-project-id returns 400 or 403, depending on the operation.
Inspect the response without logging credentials or private test data.