Quickstart

This guide walks you through getting a credential and making your first call to the NexSpace API.

Step 1: Get a credential

Self-service API-key creation is restricted to NexSpace 365 operators. Every /api/api-keys route (create, list, revoke, rotate) requires a browser session or a device-code/OAuth token — never an API key — and either the super_admin role or an admin/manager role inside the platform-internal NexSpace 365 organization. If you are an admin at a customer organization, Settings → API Keys will return 403 FORBIDDEN — “API key management is restricted to the NexSpace 365 organization”. Pick a supported path below instead.

You are	Use	How
Connecting an AI client (Claude, ChatGPT, Gemini, Cursor)	OAuth 2.1 connector flow	Any dashboard user can complete it — see Claude connector
Scripting from a terminal or CI	CLI device-code login	`nexspace login` (browser device-code, no key needed)
Building a server-to-server integration that needs a raw key	API key issued by NexSpace	Email admin@nexspace365.com to request a key for your organization
A NexSpace 365 operator	Settings → API Keys	Steps below

After an OAuth or device-code login you hold an access token that works everywhere a nex_ key does in the examples that follow — send it the same way, as Authorization: Bearer <token>.

If you can mint a key (NexSpace 365 operators)

Log in to NexSpace
Navigate to Settings → API Keys
Click Create Key
Choose your scopes. For this quickstart pick shifts:read, staff:read, facilities:read, and integrations:write (Step 4 needs that last one)
Copy the key — it’s shown only once

Your key looks like: nex_live_aBcDeFgHiJkLmNoPqRsT...

You don’t choose the prefix. The instance decides: production mints nex_live_, and the only toggle on the create form is Personal access token, which mints nex_pat_. nex_test_ (sandbox) keys are issued only by non-production NexSpace deployments — you cannot obtain one from api.nexspace365.com. See Sandbox.

Store your API key securely. Never commit it to version control or share it in client-side code.

Mintlify Try-it

On API reference pages, open Try It and paste Bearer <your credential> — an API key or PAT issued to you, or an OAuth access token from the connector / device-code flow. There is no separate sandbox URL and no shared demo credential.

Step 2: Make Your First Call

curl -H "Authorization: Bearer nex_live_YOUR_KEY" \
     https://api.nexspace365.com/api/facilities

import { NexSpace } from '@nexspace/sdk';

const client = new NexSpace({ apiKey: 'nex_live_YOUR_KEY' });
const facilities = await client.facilities.list();
console.log(facilities);

from nexspace import NexSpace

client = NexSpace(api_key="nex_live_YOUR_KEY")
facilities = client.facilities.list()
print(facilities)

nexspace login
nexspace facilities list

Step 3: Try an MCP Tool Call

AI agents interact via the MCP protocol. Here’s how to call a tool directly:

curl -X POST https://mcp.nexspace365.com/mcp \
  -H "Authorization: Bearer nex_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

This returns the full governed catalog — named workforce verbs and category tools (analytics, scheduling, CRM, and more) — regardless of what your credential is scoped for. tools/list is a discovery call, not an entitlement check; scope is enforced when you actually invoke a tool, and a call outside your scopes fails with Insufficient credential scope. The one per-caller part of the list is connected-app actions, which appear only when the credential’s bound user has an active connection to that app and the credential carries apps:read / apps:write. See MCP. To invoke one:

curl -X POST https://mcp.nexspace365.com/mcp \
  -H "Authorization: Bearer nex_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "listFacilities",
      "arguments": {}
    }
  }'

Step 4: Set Up Webhooks (Optional)

Receive real-time events when things happen in NexSpace.

This call needs the integrations:write scope. POST /api/webhooks is gated on the integrations.manage_webhooks permission, and for an API-key caller that permission resolves to the integrations:write scope (manage_webhooks is one of the write aliases). The read-only trio from Step 1 — shifts:read, staff:read, facilities:read — returns 403 INSUFFICIENT_SCOPE. Include integrations:write when you create the key, or create a second key with it. See Permission names are not scope names.

curl -X POST https://api.nexspace365.com/api/webhooks \
  -H "Authorization: Bearer nex_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "url": "https://your-app.com/webhooks/nexspace",
    "events": ["shift_filled", "credential_expired"]
  }'

The response includes a signingSecret — use it to verify incoming webhook signatures.

Next Steps

Authentication Deep Dive

OAuth 2.1, scopes, key rotation, and device-code flow.

MCP Protocol

Full MCP integration guide for AI agents.

TypeScript SDK

Install and configure the TypeScript SDK.

CLI Reference

Automate NexSpace from the command line.

Getting Started

Core Concepts

Integrations

Reference

Quickstart

Quickstart

Step 1: Get a credential

If you can mint a key (NexSpace 365 operators)

Mintlify Try-it

Step 2: Make Your First Call

Step 3: Try an MCP Tool Call

Step 4: Set Up Webhooks (Optional)

Next Steps

Authentication Deep Dive

MCP Protocol

TypeScript SDK

CLI Reference

​Quickstart

​Step 1: Get a credential

​If you can mint a key (NexSpace 365 operators)

​Mintlify Try-it

​Step 2: Make Your First Call

​Step 3: Try an MCP Tool Call

​Step 4: Set Up Webhooks (Optional)

​Next Steps

Authentication Deep Dive

MCP Protocol

TypeScript SDK

CLI Reference

Quickstart

Step 1: Get a credential

If you can mint a key (NexSpace 365 operators)

Mintlify Try-it

Step 2: Make Your First Call

Step 3: Try an MCP Tool Call

Step 4: Set Up Webhooks (Optional)

Next Steps