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"]
  },
  "account": {
    "kind": "BUSINESS",
    "features": { "team": true, "apps": true, "apiKeys": true, "campaigns": true, "listings": true, "valuations": true, "pricingRules": true },
    "limits": { "listings": null, "valuations": null, "teamMembers": null, "campaignEmailsPerMonth": null, "cedarAnswersPerDay": null },
    "used": { "listings": 0, "valuations": 0, "teamMembers": 4, "campaignEmailsPerMonth": 1250 }
  },
  "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,
    "expiresAt": "2026-11-02T13:00:00.000Z",
    "expired": false
  },
  "accountManager": {
    "id": "clx…",
    "name": "Carla Reyes",
    "email": "carla@getcypress.ai"
  },
  "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 }
}

Individual and business accounts

account is your account's rules as they hold for your organization. Since 1.9.0.

• kind: BUSINESS (a dealer or fleet) or INDIVIDUAL (a private person's account, from Grove's front door or the private-buyer sign-up). An individual works as a dealer does, within its caps, and can ask Cypress to become one.
• features: which features are on: the team, connecting apps, API keys, pricing rules, marketing campaigns, valuations and listings, and the rest. Planning, Buy planning, Automations, the channels, ACH and bank transfer keep their own switches (products, channels, billing).
• limits: the caps, null for none: cars listed and valuations in total (a car counts the first time it is listed), people in the account (owner included), campaign emails a month, Cedar's answers a day in Grove.
• used: what your organization used of them.

Cypress sets the rules for each kind of account and can change them for your organization. By default a business has every feature and no caps; an individual lists 10 cars and runs 10 valuations in total, has a team of 3, and sends campaigns once Cypress switches them on (500 emails a month). What they refuse answers ACCOUNT_RULES (403), on the route and in capabilities alike; see Errors. An individual values, lists, invites people, connects apps and makes API keys once its email is confirmed.

Your Cypress Manager

accountManager is the person at Cypress who looks after your organization: their id, name and email, and nothing else. It is null while no one is assigned. Any credential of your organization reads it, people's and agents' alike, so an app can show who to contact. get_organization_profile (GET /api/v1/organization/profile, scope organization:read) answers it too. Since 1.9.0.

What Cypress may do for you, and until when

delegation is what your organization lets Cypress do, as it stands now. Your admin sets it with set_cypress_delegation (PATCH /api/v1/organization/delegation, scope organization:write): the three switches and, since 1.9.0, an end date, expiresAt (a moment in the future, or null for none). From that moment every switch reads as off everywhere, and expired is true; the change is told as ORGANIZATION.UPDATED with change: "DELEGATION", the switches' from and to, and expiresAt.

curl -X PATCH "$BASE/api/v1/organization/delegation" \
  -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{ "allowCMReviewOfferDecisions": true, "expiresAt": "2026-11-02T13:00:00Z" }'

A switch granted again after its end date passed, with no new end date, is granted without one; the switches you leave out stay off. It is your admins' act, through an app acting for them: an API key, an agent and Cypress staff are refused.

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.