Sample Knowledge Base
Back to AgileDocs
Developers / Authentication
Reviewed

API authentication: API keys vs OAuth 2.0

authenticationapi-keysoauthsecurity
Versionv2.3 AudienceDevelopers OwnerPlatform Team Last reviewedJun 2026 ConfidenceHigh Citations4

Northwind Cloud supports two authentication methods for its REST API: long-lived API keys for server-to-server integrations, and OAuth 2.0 for apps acting on behalf of a user. Choose based on who the request represents, not on convenience.

Use an API key when your backend acts as itself. Use OAuth when your app acts as a specific Northwind user and needs their permission scope.

API keys

Generate a key under Settings → API keys. Pass it as a bearer token on every request. Keys inherit the permissions of the service account that created them.

# server-to-server request
curl https://api.northwind.cloud/v2/projects \
  -H "Authorization: Bearer nw_live_8f3a…"

OAuth 2.0

Register an OAuth client, then run the standard authorization-code flow. Request only the scopes you need; users see and approve them on the consent screen.

  1. Redirect the user to /oauth/authorize with your client_id and scopes.
  2. Exchange the returned code at /oauth/token for an access token.
  3. Refresh tokens before they expire (default 8 hours).

Choosing between them

 API keyOAuth 2.0
Acts asA service accountA specific user
Best forBackend jobs, integrationsUser-facing apps
Scope controlService permissionsPer-user consent
Token lifeLong-livedShort, refreshable
Never embed an API key in client-side code or a mobile app. Treat keys as secrets and rotate them on staff offboarding.
Machine-readable metadata 
{
  "id": "api-auth",
  "version": "2.3",
  "audience": ["developers"],
  "owner": "platform-team",
  "last_reviewed": "2026-06-02",
  "next_review": "2026-12-02",
  "confidence": "high",
  "citations": 4,
  "tags": ["authentication", "oauth"]
}

Sources / citations

  1. Northwind API Reference, “Authentication” (internal, v2.3)
  2. Security Standard SEC-014: Secret handling & rotation
  3. RFC 6749 — The OAuth 2.0 Authorization Framework
  4. Platform Team decision log, 2026-05-19

Related articles

Webhooks: events & verificationDevelopers · v1.6 Rate limits & quotasDevelopers · v1.2
Was this helpful?
Developers / Events
Reviewed

Webhooks: events & verification

webhookseventssignaturesretries
Versionv1.6 AudienceDevelopers OwnerPlatform Team Last reviewedMay 2026 ConfidenceHigh Citations3

Webhooks push real-time events to a URL you control, so you don't poll the API. Northwind signs every delivery; your endpoint must verify the signature and respond quickly.

Subscribing to events

Create an endpoint under Settings → Webhooks and select the events you care about, for example project.created or member.removed.

Verifying signatures

Each request includes an X-NW-Signature header: an HMAC-SHA256 of the raw body using your endpoint's signing secret. Compute the same HMAC and compare in constant time before trusting the payload.

# pseudo-verification
expected = hmac_sha256(secret, raw_body)
if not constant_time_eq(expected, header): reject(400)
Respond 2xx within 5 seconds. Do slow work in a background job — Northwind treats a timeout as a failed delivery.

Retries & ordering

  • Failed deliveries retry with exponential backoff for up to 24 hours.
  • Events are not strictly ordered; use the event id and created_at to de-duplicate and sequence.
  • Replay any event from the dashboard for 30 days.
Machine-readable metadata 
{
  "id": "webhooks",
  "version": "1.6",
  "audience": ["developers"],
  "owner": "platform-team",
  "last_reviewed": "2026-05-12",
  "confidence": "high",
  "tags": ["webhooks", "events", "signatures"]
}

Sources / citations

  1. Northwind API Reference, “Webhooks”
  2. Security Standard SEC-014: Signature verification
  3. Platform reliability runbook REL-007

Related articles

API authenticationDevelopers · v2.3 Rate limits & quotasDevelopers · v1.2
Was this helpful?
Developers / Limits
Review due

Rate limits & quotas

rate-limitsquotas429
Versionv1.2 AudienceDevelopers OwnerPlatform Team Last reviewedDec 2025 ConfidenceMedium Citations2
This article is past its review date — limits below are being revised for the v3 API and may change.

Default limits

PlanRequests / minBurst
Free60120
Team6001,200
EnterpriseCustomCustom

Handling 429s

When you exceed a limit the API returns 429 Too Many Requests with a Retry-After header. Back off for that many seconds, then retry with jitter.

Machine-readable metadata 
{
  "id": "rate-limits",
  "version": "1.2",
  "owner": "platform-team",
  "last_reviewed": "2025-12-01",
  "next_review": "2026-06-01",
  "confidence": "medium",
  "status": "review-due"
}

Sources / citations

  1. Northwind API Reference, “Rate limiting”
  2. Gateway config (Infra), 2025-12

Related articles

API authenticationDevelopers · v2.3 WebhooksDevelopers · v1.6
Was this helpful?
Support / Accounts
Reviewed

Resetting a workspace member's password

passwordrecoverysupport
Versionv1.4 AudienceSupport OwnerSupport Ops Last reviewedMay 2026 ConfidenceHigh Citations2

Members can reset their own password from the sign-in screen. Use the admin-assisted flow only when a member has lost access to their email or an admin requests it on their behalf.

Self-service reset

  1. On the sign-in page, the member selects Forgot password.
  2. Northwind emails a single-use link, valid for 30 minutes.
  3. The member sets a new password meeting the policy (12+ characters).

Admin-assisted reset

  1. Verify the requester's identity per the support verification script.
  2. In Admin → Members, open the member and choose Send reset link.
  3. Never set a password on a member's behalf; the system does not support it by design.
If the account shows multiple failed reset attempts, escalate to Security before sending another link.
Machine-readable metadata 
{
  "id": "reset-password",
  "version": "1.4",
  "audience": ["support"],
  "owner": "support-ops",
  "last_reviewed": "2026-05-04",
  "confidence": "high"
}

Sources / citations

  1. Support Runbook SUP-022: Account recovery
  2. Identity Policy IDP-003: Password requirements
Was this helpful?
Compliance / Data lifecycle
Review due

Data retention and deletion

retentiondeletionprivacybackups
Versionv3.0 AudienceCompliance & Admins OwnerSecurity & Compliance Last reviewedApr 2026 ConfidenceMedium Citations3

Northwind retains customer data only as long as needed to provide the service or to meet a legal obligation. This article summarizes default retention windows and how deletion requests are handled.

Confidence is Medium: the legal-hold exception is under review with counsel and may change in the next revision.

Default retention

DataWindow
Active workspace dataLife of subscription
Deleted items30 days, then purged
Audit logs12 months
BackupsRolling 35 days

Deletion requests

  1. An admin submits the request from Settings → Privacy.
  2. Northwind confirms, then removes data from production within 30 days and from backups within 35.
  3. Data under an active legal hold is exempt until the hold is lifted.
Machine-readable metadata 
{
  "id": "data-retention",
  "version": "3.0",
  "audience": ["compliance", "admins"],
  "owner": "security-compliance",
  "last_reviewed": "2026-04-09",
  "confidence": "medium"
}

Sources / citations

  1. Data Retention Schedule DRS-2026
  2. DPA, Section 7 — Deletion & return of data
  3. Subprocessor backup policy (Infra)
Was this helpful?
Admin / Onboarding
Reviewed

Provisioning a new workspace

workspaceonboardingseatssso
Versionv1.1 AudienceAdmins OwnerOnboarding Last reviewedMar 2026 ConfidenceHigh Citations1

A workspace is the top-level container for a customer's projects, members, and billing. Provisioning takes about five minutes and should be done by an account owner.

Steps

  1. From the org console, choose New workspace and name it after the customer.
  2. Set the plan tier and seat limit; these can be changed later.
  3. Invite the customer's first admin by email. They complete setup.
  4. Confirm SSO settings if the customer is on an Enterprise plan.
Seat limits are soft by default — members above the limit are flagged for billing rather than blocked. Toggle hard limits per workspace if required.
Machine-readable metadata 
{
  "id": "provision-workspace",
  "version": "1.1",
  "audience": ["admins"],
  "owner": "onboarding",
  "last_reviewed": "2026-03-18",
  "confidence": "high"
}

Sources / citations

  1. Onboarding Playbook OB-009: New customer setup
Was this helpful?