Getting Started

Set up the account, organization and API key that every product in these docs uses.

Everything is provisioned per organization: you create an org, enable products, create API keys scoped to those products, and every credential, project and portal lives under that org. Each product section assumes you have done the steps on this page.

Create your account and organizationlink

Sign up at https://www.newinstance.cloud to create your account.
Log in to the merchant dashboard at https://dashboard.newinstance.cloud.
Create an Organization (org). All products are provisioned per org.

Base URLs and environmentslink

Host	Serves	Placeholder
`https://api.newinstance.cloud`	REST API: every request in this reference unless stated otherwise	`{{baseUrl}}`
`https://service.newinstance.cloud`	MCP agent endpoint (AI Agent Access (MCP))	`{{serviceUrl}}`
`https://widget.newinstance.cloud`	Chat widget embed script (Chat)	None

There is no separate sandbox host. Test safely against the same production URL with a test-mode key (sk_test_…): test and live keys are stored in physically separate keyspaces server-side, so test-key traffic can never read or write live data. Switch to a sk_live_… key when you go to production.

The environment value used throughout this reference is a data label you attach to events (production / staging / development) and the Secret Manager environment selector. It does not change which host you call.

Generate a central API keylink

API keys are created at Dashboard → Org → API Keys (/dashboard/org/[orgId]/api-keys).

Key format: sk_test_<keyId>:<secret> (test) or sk_live_<keyId>:<secret> (live)

The full keyId:secret string is shown once, so copy it immediately.

Security rule: The keyId:secret form is for server-to-server calls only. Never embed it in browser code, mobile apps, or client-side scripts.

Permission scopeslink

When creating a key you choose which product(s) and permission groups it covers. Each product has its own scope codes:

BugWatch scopeslink

Scope code	What it grants
`ingest:write`	Send events: server ingest, browser-session mint, browser ingest, mobile ingest, OTLP, Prometheus, RUM
`deploy:write`	Report CI deployments, stage transitions and deploy logs (Deployments (CI/CD))
`symbols:upload`	Upload R8/ProGuard/dSYM/source-map artifacts at build time
`symbols:read`	List and poll debug symbol uploads
`symbols:reprocess`	Re-symbolicate crashes after uploading late symbols
`symbols:delete`	Delete symbol uploads (dashboard operation; no public REST endpoint)
`error-ingestion` / `log-access` / `analytics-access` / `read-only`	Dashboard-style read/ingest splits for reporting keys. Issue/log reads are served by the dashboard and the MCP agent endpoint; there is no public REST read API for them
`ingest`	Legacy code that grants full BugWatch access (kept for old keys; prefer the granular codes)
`full-access` / `bugwatch-admin`	All BugWatch permissions

Support Tickets scopeslink

Scope code	What it grants
`full-access`	All support-ticket permissions (recommended)
`ticket-management`	Create, read, update, assign, close tickets
`ticket-configuration`	Read/write ticket configuration (managed from the dashboard; no public REST endpoint)
`read-only`	Read tickets and config only

Secret Manager scopeslink

Scope code	What it grants
`full-access` / `secret-admin`	All secret-manager permissions
`secret-read`	Fetch MEK and encrypted variables (what your runtime needs)
`secret-write`	Create/update encrypted variables (writes happen from the dashboard or `nism`; the public REST surface is read-only)
`secret-rotation`	Read/write rotation state (dashboard-managed)
`read-only`	Secret metadata only (no values)

Chat scopeslink

Scope code	What it grants
`full-access`	All chat permissions
`ai-chatbot-access`	Interact with the AI chatbot
`ai-chatbot-configuration`	Configure/train the AI chatbot
`live-chat-operations`	Manage live chat sessions
`chat-configuration`	Configure widget settings
`read-only`	Read chats and config only

Docs Portal scopeslink

Scope code	What it grants
`full-access`	All docs-portal permissions
`content-management`	Create / edit / delete pages and sections
`publish-management`	Publish / unpublish portals and pages
`api-reference-management`	Import and manage OpenAPI specs
`portal-configuration`	Branding, theming, layout, SEO
`domain-management`	Manage custom domains and DNS
`read-only`	Read-only access

Docs Portal authoring is dashboard-driven today: these scopes govern keys used by platform surfaces, and there is no public REST authoring API (see Docs Portal).

The authentication schemeslink

Scheme	Header	Used by
Central API key	`x-api-key: sk_live_KEYID:secret`	Server-side calls for all products, including the MCP agent endpoint. `Authorization: Bearer KEYID:secret` is also accepted on BugWatch ingest, OTLP and MCP.
Chat customer token	`Authorization: Bearer <token>`	Chat widget and chat mobile SDKs 0.4.0+ in customer token mode (recommended). Minted by your server with `POST /api/v1/chat/sessions`, so the secret never ships
Chat key mode	`x-api-key: sk_live_KEYID:secret`	Chat widget and chat mobile SDKs 0.4.0+ in key mode. Ships the secret inside the client, so trusted internal apps only
Bare key ID (deprecated)	`x-api-key: sk_live_KEYID` (no secret)	Deployed web embeds and chat SDKs below 0.4.0. Still accepted from those clients so nothing deployed breaks; do not use it for new integrations
Browser session token	`x-bugwatch-session: <token>`	BugWatch browser SDK + RUM. Minted server-side (1 h TTL), sent by the SDK
Mobile token	`x-bugwatch-token: <token>`	Signed on device by the BugWatch mobile SDKs (5 min expiry); the secret never ships or transits. The token format is internal to the SDKs, not a public signing contract, so use a mobile SDK rather than minting these yourself

Placeholders used in the exampleslink

Placeholder	Description	Secret?
`baseUrl`	REST API base URL, `https://api.newinstance.cloud`	No
`serviceUrl`	MCP agent endpoint host, `https://service.newinstance.cloud`	No
`apiKey`	`sk_test_KEYID:secret` or `sk_live_KEYID:secret`, copied from the dashboard	YES
`projectId`	BugWatch project public ID	No
`appId`	Secret Manager app ID	No
`environment`	Event environment label (`production`/`staging`/`development`)	No
`release`	App release version e.g. `2.1.0`	No
`sessionToken`	Returned by "Mint browser session token"	No
`uploadId`	Returned by the symbol presign endpoints	No
`deployId`	Returned by "Start deployment"	No
`ticketId`	Returned by "Create ticket"	No

Verify API key

GET/api/auth/verify

Checks that your API key is valid and returns the organization it belongs to and its environment.

Run this first after generating a key to confirm it is active and to see whether it is a test or a live key. A malformed or revoked key is refused the same way as a missing one.

Authorization

x-api-keyAPI key · headerrequired

Responses

200Key valid

401Invalid or missing API key

403Key inactive

curl -X GET 'https://api.newinstance.cloud/api/auth/verify' \
  -H 'x-api-key: YOUR_API_KEY'

Response

{
  "success": true,
  "message": "API key is valid",
  "business": {
    "id": "org_abc123",
    "name": "Acme Corp",
    "slug": "acme-corp"
  },
  "key": {
    "id": "sk_test_abc123",
    "environment": "test"
  },
  "timestamp": "2026-06-26T10:00:00.000Z"
}