Your organization and key

GET /api/v1/organization

Answers any valid, unrevoked key — whatever your organization's status. Every other route on both surfaces still requires an active organization; this one exists so a key for an organization still onboarding (or between plans) can learn why everything else is refused, instead of guessing from a 403.

What it returns

{
  "organization": {
    "id": "org_9f3a…",
    "name": "Meridian Fleet Partners",
    "slug": "meridian-fleet",
    "status": "ACTIVE",
    "profiles": ["SELLER"]
  },
  "apiKey": {
    "id": "key_2b71…",
    "name": "ERP integration",
    "scopes": ["vehicles", "listings", "webhooks", "planning:read"],
    "createdAt": "2026-08-19T14:02:00.000Z"
  },
  "products": {
    "remarketing": { "enabled": true },
    "planning": { "enabled": true, "requestedAt": "2026-07-01T00:00:00.000Z" },
    "buyPlanning": { "enabled": false, "requestedAt": null },
    "automations": { "enabled": false }
  },
  "channels": [
    { "channel": "MARKETPLACE", "enabled": true },
    { "channel": "STOREFRONT", "enabled": true, "published": true },
    { "channel": "DIRECT_LINK", "enabled": false }
  ],
  "billing": {
    "standing": "CURRENT",
    "autoPay": "ACH"
  },
  "delegation": {
    "cypressMayActOnBehalf": false,
    "cypressDecidesReviewOffers": true,
    "cypressMayMakeBuyerOffers": false
  },
  "capabilities": [
    { "capability": "vehicles.read", "allowed": true },
    { "capability": "vehicles.write", "allowed": true },
    { "capability": "listings.read", "allowed": true },
    { "capability": "listings.write", "allowed": true },
    { "capability": "listings.channel.MARKETPLACE", "allowed": true },
    { "capability": "listings.channel.STOREFRONT", "allowed": true },
    { "capability": "listings.channel.DIRECT_LINK", "allowed": false, "reason": "CHANNEL_NOT_GRANTED" },
    { "capability": "webhooks.manage", "allowed": true },
    { "capability": "planning.read", "allowed": true },
    { "capability": "planning.write", "allowed": false, "reason": "SCOPE_MISSING" },
    { "capability": "buy-planning.read", "allowed": false, "reason": "BUY_PLANNING_NOT_ENABLED" },
    { "capability": "buy-planning.write", "allowed": false, "reason": "BUY_PLANNING_NOT_ENABLED" }
  ],
  "rateLimit": { "requestsPerMinute": 300 }
}

Reading capabilities

Each entry names one thing this key could do, and — when it's refused — the same reason code the refusing route would return. Switch on reason:

A capability with allowed: true carries no reason.

Live and test keys

A key's first characters say where it acts. Since 1.5.0.

Cypress holds a key to its environment: a test key on a live organization, or a live key on a sandbox, answers 403 KEY_ENVIRONMENT and does nothing. Never test with a live key: build against a sandbox's test key, and use the live key only in the system that runs your integration.

A key is cyp_live_ or cyp_test_, then 32 letters and digits, an underscore, and a 6-character checksum (the CRC-32 of everything before the underscore, in base 62). A key whose checksum does not match is refused before Cypress looks it up, and a secret scanner can recognize a real key with cyp_(live|test)_[A-Za-z0-9]{32}_[A-Za-z0-9]{6}. Keys made before 1.5.0 (cyp_live_ and 32 characters, no checksum) keep working as they did; make a new one to get the checksum. If a key is ever pasted anywhere it should not be, revoke it in Organization → Integrations and make another.

Key scopes

There are two planning products, and they are separate. products.planning, the planning:read / planning:write scopes and the planning.* capabilities mean Sell planning, the plan that hands vehicles to Sell. products.buyPlanning, the buy-planning:read / buy-planning:write scopes and the buy-planning.* capabilities mean Buy planning, the dealer's plan. Each has its own switch: an organization with Buy planning but not Sell planning answers 403 PLANNING_NOT_ENABLED on the Sell planning routes, and one with Sell planning but not Buy planning answers 403 BUY_PLANNING_NOT_ENABLED on the Buy planning routes. The scope strings never changed; since 1.4.0 the Integrations page labels them "Sell planning (read)", "Sell planning (read and write)", "Buy planning (read)" and "Buy planning (read and write)".

A key created without picking scopes gets the defaults — vehicles, listings, webhooks — never a planning scope, sell or buy. Scopes are chosen at mint and can be changed later from the Integrations page without rotating the key; every existing key keeps exactly the scopes it already has.

An embedded listing on a vehicle push (POST /api/v1/vehicles, its bulk form, and the Manheim-compatible offering on POST /api/compatible/v1/units) needs the listings scope too — vehicles alone lets you push the vehicle but not the listing riding along with it; without listings the push (or that bulk item) answers 403 SCOPE_MISSING and creates nothing.