Authentication

All API requests require authentication via a Bearer token in the Authorization header.

API Key Format

Authorization: Bearer nds_live_aBcDeFgHiJkLmNoPqRs

nodestash uses prefixed API keys for easy identification:

Prefix	Environment	Purpose
`nds_live_`	Production	Real data, production workloads
`nds_test_`	Test	Testing and development

API keys are shown only once when created. Store them securely — you cannot retrieve the full key later.

Making Authenticated Requests

curl https://api.nodestash.io/v1/contacts \
  -H "Authorization: Bearer nds_live_your_key_here"

import { NodeStash } from '@nodestash/sdk'

const client = new NodeStash({
  apiKey: 'nds_live_your_key_here',
})

const { data } = await client.contacts.list()

Scopes

API keys can be restricted to specific operations using scopes. Scopes follow the pattern {resource}:{action}.

Available Scopes

Scope	Access
`*`	Full access to all endpoints
`contacts:read`	Read contacts
`contacts:write`	Create, update, delete contacts
`companies:read`	Read companies
`companies:write`	Create, update, delete companies
`deals:read`	Read deals
`deals:write`	Create, update, delete deals
`pipelines:read`	Read pipelines and stages
`pipelines:write`	Create, update, delete pipelines and stages
`activities:read`	Read activities
`activities:write`	Create, update, delete activities
`custom_fields:read`	Read custom field definitions and values
`custom_fields`	Full access to custom field definitions and values

Creating a Scoped Key

curl -X POST https://api.nodestash.io/v1/api-keys \
  -H "Authorization: Bearer $NODESTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Read-only Dashboard",
    "scopes": ["contacts:read", "companies:read", "deals:read"]
  }'

const key = await client.apiKeys.create({
  name: 'Read-only Dashboard',
  scopes: ['contacts:read', 'companies:read', 'deals:read'],
})

console.log(key.key) // nds_live_... (only shown once)

If a request requires a scope that the key doesn't have, the API returns a 403 error:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "API key does not have the required scope: activities:read"
  },
  "meta": {
    "request_id": "req_abc123def456ghi789jkl012"
  }
}

Key Expiration

API keys can have an optional expiration date. Expired keys return a 401 error.

curl -X POST https://api.nodestash.io/v1/api-keys \
  -H "Authorization: Bearer $NODESTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Temporary Integration Key",
    "scopes": ["contacts:read", "contacts:write"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'

const key = await client.apiKeys.create({
  name: 'Temporary Integration Key',
  scopes: ['contacts:read', 'contacts:write'],
  expires_at: '2026-12-31T23:59:59Z',
})

Security Best Practices

Follow these practices to keep your API keys secure.

Use environment variables — never hard-code keys in source code
Scope keys narrowly — grant only the permissions each integration needs
Rotate keys regularly — create new keys and revoke old ones periodically
Set expiration dates — especially for keys shared with third parties
Use test keys for development — keep production keys separate
Monitor usage — check last_used_at to identify inactive keys

Error Responses

Status	Code	Meaning
`401`	`MISSING_AUTH`	No `Authorization` header provided
`401`	`INVALID_API_KEY`	Key not found, revoked, or expired
`403`	`INSUFFICIENT_SCOPE`	Key lacks required scope

On this page