Skip to content
Nx Cloud CI is in private beta 10.6× faster average CI time with 79% less compute. Join the beta
Back to Knowledge Base

Authenticate with the Nx Cloud Public API

Call the Public API with npx nx-cloud api from your workspace, in a terminal or a script. It authenticates with your login from npx nx login, or with a CI access token.

To send requests without the Nx Cloud CLI, use one of these credentials:

  • A CI access token, sent as a bearer token.
  • A personal access token (PAT) and Nx Cloud Id, sent together in two headers.

The Nx Cloud Id alone does not authenticate a Public API request. Service-account credentials for the Prometheus metrics API do not authenticate Public API requests.

Terminal window
npx nx-cloud api cipes

The command sends the login stored on your machine, with the nxCloudId from your nx.json, and refreshes an OAuth login when it expires. If you aren't logged in, run npx nx login and approve the code in your browser.

In CI, set NX_CLOUD_ACCESS_TOKEN to a CI access token. Whenever that variable is set, the command sends it instead of your login.

Run npx nx-cloud api --help for paths, filters, and pagination.

The organization must be enabled, and your credential must have access to the workspace.

All workspaces and access tokens in an organization share one request quota, and the organization's plan sets its default:

PlanRequests per minute
Free, Legacy30
Team, Pro, OSS60
Enterprise2,500

A request over the quota returns 429 with the error code rate_limit_exceeded. Wait the number of seconds in the Retry-After header before you retry.

Use the host that serves your workspace:

  • https://cloud.nx.app for the US region.
  • https://eu.nx.app for the EU region.
  • Your deployment URL for a single-tenant installation.

The examples below require curl and jq. They discover the CI pipeline execution (CIPE) collection path from your deployment, so they do not assume an API version.

Terminal window
export NX_CLOUD_HOST="https://cloud.nx.app"
curl --fail --silent --show-error \
"$NX_CLOUD_HOST/nx-cloud/data/openapi.json" \
--output openapi.json
CIPES_PATH=$(jq -r '.paths | keys[] | select(endswith("/cipes"))' openapi.json)

Create a CI access token in your Nx Cloud workspace settings, under Access Control. See CI access tokens for token management.

Store the token in your secret manager. Provide it to your shell or CI environment as NX_CLOUD_ACCESS_TOKEN.

Send the token in the Authorization header:

Terminal window
curl --fail-with-body --silent --show-error --get \
"$NX_CLOUD_HOST$CIPES_PATH" \
--header "Authorization: Bearer $NX_CLOUD_ACCESS_TOKEN" \
--data-urlencode "limit=10"

The token identifies its workspace. This option does not require an Nx-Cloud-Id header.

Use a personal access token and Nx Cloud Id

Section titled “Use a personal access token and Nx Cloud Id”

Use a PAT for a script that acts as you and can't run the Nx Cloud CLI. Create one in Nx Cloud under Personal settings > Access tokens.

Store the PAT in your secret manager. Provide it to your script as NX_CLOUD_PERSONAL_ACCESS_TOKEN.

Find the Nx Cloud Id in the nxCloudId property of your workspace's nx.json, or in the workspace's General settings. Set NX_CLOUD_WORKSPACE_ID to that value:

Terminal window
export NX_CLOUD_WORKSPACE_ID="<nx-cloud-id>"

Send both headers in the same request:

Terminal window
curl --fail-with-body --silent --show-error --get \
"$NX_CLOUD_HOST$CIPES_PATH" \
--header "Nx-Cloud-Personal-Access-Token: $NX_CLOUD_PERSONAL_ACCESS_TOKEN" \
--header "Nx-Cloud-Id: $NX_CLOUD_WORKSPACE_ID" \
--data-urlencode "limit=10"

The PAT and Nx Cloud Id are required together. Use these two headers instead of the CI bearer header.

Do not commit tokens to your repository or include them in logs, prompts, or reports. Send credentials only to your Nx Cloud API host. Do not forward them to signed asset-download URLs.

If a request returns 401, check the token and its header. For PAT authentication, check that both the PAT and Nx Cloud Id headers are present.

See Query the Nx Cloud Public API for filters, pagination, and asset downloads. Use the API reference to look up endpoints, response schemas, and errors.

Last updated: