Authentication

NexSpace supports three authentication methods. Choose based on your use case.

Method	Best For	How
API Key	Server-to-server, agents, CI/CD	`Authorization: Bearer nex_live_...`
OAuth 2.1 + PKCE	Browser-based apps, plugins	Authorization code flow with S256
Device Code	CLI tools, headless environments	Poll-based flow (RFC 8628)

API Keys

API keys are the simplest way to authenticate. Each key has scopes that control what it can access.

Key Prefixes

Prefix	Environment	Purpose
`nex_live_`	Production	Server-to-server integrations
`nex_test_`	Sandbox	Development and testing
`nex_pat_`	Production	Personal access tokens (acts as issuing user)

Sandbox keys share the production database but only see is_sandbox rows, skip real notifications and outbound platform webhooks, and are omitted from usage analytics totals. See Sandbox (test API keys) for isolation rules, TTL, and scope limits.

Scopes

Scopes follow the pattern resource:action. Wildcard resource:* grants all actions on a resource.

Scope	Description
`shifts:read`	Read shifts and schedules
`shifts:write`	Create and modify shifts
`shifts:assign`	Assign staff to shifts
`staff:read`	Read staff profiles
`staff:write`	Create and modify staff records
`credentials:read`	Read credentials
`credentials:verify`	Run credential verification
`payroll:read`	Read payroll data
`payroll:run`	Execute payroll
`crm:*`	All CRM operations
`facilities:read`	Read facility data
`*`	Full access (use sparingly)

Key Rotation

Rotate keys with zero downtime — the old key remains valid for 24 hours:

curl -X POST https://api.nexspace365.com/api/api-keys/{id}/rotate \
  -H "Authorization: Bearer nex_live_YOUR_KEY"

OAuth 2.1 + PKCE

For apps where users grant access through a browser flow.

Discovery

curl https://api.nexspace365.com/.well-known/oauth-authorization-server

Dynamic Client Registration (RFC 7591)

Clients can self-register without operator intervention:

curl -X POST https://api.nexspace365.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My App",
    "redirect_uris": ["https://myapp.com/callback"],
    "scope": "shifts:read staff:read facilities:read"
  }'

Authorization Flow

Redirect user to /oauth/authorize with PKCE code_challenge (S256)
User logs in and grants scopes
Exchange code + code_verifier at /oauth/token
Receive access_token + refresh_token

Device Code Flow (RFC 8628)

For CLI tools and environments without a browser.

# 1. Request a device code
curl -X POST https://api.nexspace365.com/oauth/device/code \
  -H "Content-Type: application/json" \
  -d '{"client_id": "YOUR_CLIENT_ID", "scope": "shifts:read staff:read"}'

# Response includes user_code and verification_uri
# 2. User opens verification_uri in browser, enters user_code
# 3. CLI polls /oauth/token with device_code until approved

The NexSpace CLI handles this automatically. nexspace login runs the device-code flow by default (opening your browser); pass --token nex_pat_… to store a personal access token instead:

nexspace login                 # browser OAuth (device code)
nexspace login-device          # explicit alias for the same flow
nexspace login --token nex_pat_xxxxxxxxxxxxxxxxxxxxxxxx

Credentials are stored in your OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager) when available, falling back to ~/.nexspace/config.json (mode 0600). The CLI refreshes the OAuth access token automatically as it nears expiry, rotating the stored refresh token.

Verify identity

GET /api/auth/me returns the identity a credential authenticates as. It accepts any supported credential — API key (nex_live_/nex_test_), personal access token (nex_pat_), OAuth 2.1 access token, or first-party session — so it’s the canonical “who am I” probe for SDKs, MCP clients, and the CLI (nexspace whoami).

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

{
  "user": {
    "id": 42,
    "email": "ops@acme.com",
    "username": "acme-ops",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "role": "facility_admin"
  }
}

A missing or revoked credential returns 401.

Token Introspection (RFC 7662)

Resource servers can check whether a token is active and inspect its metadata. The caller authenticates as the client that owns the token — public clients (PKCE: CLIs, SPAs) present client_id alone; confidential clients also present client_secret. Works for both access tokens (JWT) and refresh tokens.

curl -X POST https://api.nexspace365.com/oauth/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID"

An active token returns its metadata; an unknown, expired, revoked, or foreign-owned token returns { "active": false } (never an error):

{
  "active": true,
  "scope": "shifts:read staff:read",
  "client_id": "nexspace_cli_public",
  "token_type": "Bearer",
  "sub": "42",
  "exp": 1751990400,
  "iat": 1751986800
}

Token Revocation (RFC 7009)

Revoke a token when a session ends or a credential is compromised. Revoking a refresh token invalidates it and its entire rotation chain; revoking an access token invalidates the associated refresh chain so it can’t be renewed (the stateless access JWT itself remains valid until its short 1-hour exp). Per RFC 7009 the response is always 200 with an empty body.

curl -X POST https://api.nexspace365.com/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=REFRESH_TOKEN&client_id=YOUR_CLIENT_ID"

nexspace logout clears stored credentials locally (keychain + config file).

Rate Limits

Every API response includes rate-limit headers:

Header	Description
`X-RateLimit-Limit`	Requests allowed per window
`X-RateLimit-Remaining`	Requests remaining
`X-RateLimit-Reset`	When the window resets (Unix timestamp)

Default: 60 requests/minute per API key. Configurable per key up to 6,000/min.

Error Responses

Authentication errors return structured JSON with recovery hints:

{
  "error": {
    "message": "Invalid API key",
    "code": "INVALID_API_KEY",
    "suggestion": "Check that your key starts with nex_live_, nex_test_, or nex_pat_ and has not been revoked.",
    "retryable": false
  }
}

Getting Started

Core Concepts

Integrations

Reference

Authentication

Authentication

API Keys

Key Prefixes

Scopes

Key Rotation

OAuth 2.1 + PKCE

Discovery

Dynamic Client Registration (RFC 7591)

Authorization Flow

Device Code Flow (RFC 8628)

Verify identity

Token Introspection (RFC 7662)

Token Revocation (RFC 7009)

Rate Limits

Error Responses

​Authentication

​API Keys

​Key Prefixes

​Scopes

​Key Rotation

​OAuth 2.1 + PKCE

​Discovery

​Dynamic Client Registration (RFC 7591)

​Authorization Flow

​Device Code Flow (RFC 8628)

​Verify identity

​Token Introspection (RFC 7662)

​Token Revocation (RFC 7009)

​Rate Limits

​Error Responses

Authentication

API Keys

Key Prefixes

Scopes

Key Rotation

OAuth 2.1 + PKCE

Discovery

Dynamic Client Registration (RFC 7591)

Authorization Flow

Device Code Flow (RFC 8628)

Verify identity

Token Introspection (RFC 7662)

Token Revocation (RFC 7009)

Rate Limits

Error Responses