Skip to main content
Portfolio isolation is an opt-in account setting that locks every API key to the portfolio it was created in. Once enabled, a key can’t read or act on other portfolios unless it has cross portfolio access. Use it when different clients, desks, or teams each have their own portfolio and one party’s key must never see another’s balances, orders, transfers, or reports. For example, a broker can give each downstream client its own portfolio and key.

​
Terminology

Some API responses call a key with cross portfolio access a Managed key. The Exchange web interface always uses Cross Portfolio Access. They mean the same thing.

​
How it works

​
Isolation off (default)

Order entry, FIX, and WebSocket already limit each key to its own portfolio. REST access depends on the endpoint. Some endpoints return account-wide results, while others use the portfolio the API key was created in (its bound portfolio), even if you supply another profile_id. A key with cross portfolio access retains the same behavior when isolation is on. For orders, supplying a user_id that matches the authenticated user can widen the list across portfolios when isolation is off or the key has cross portfolio access. This is separate from selecting a portfolio with profile_id. Isolated portfolio-scoped keys cannot widen the list this way.

​
Isolation on

  • Portfolio-scoped keys are limited to their own portfolio. Get profiles returns one portfolio, and GET /accounts/all returns only that portfolio’s accounts.
  • Keys with cross portfolio access retain the endpoint-specific behavior above, including the existing restrictions on profile_id selection.
  • Order entry, FIX, and WebSocket don’t change.
  • Web sign-in doesn’t change. Isolation applies to API keys only.
Response behavior depends on the endpoint:
  • List requests for orders, transfers, conversions, and reports can return 200 OK with the key’s own portfolio data even when you supply another profile_id. The supplied selector does not change the portfolio used. Isolated report lists exclude reports without a matching profile.
  • A ledger request for an account in another portfolio returns 404 Not Found, including for keys with cross portfolio access.
  • Account-level endpoints that isolation blocks, such as GET /payment-methods and GET /fees, return 403 Forbidden for portfolio-scoped keys.
Do not use a 200 response as proof that the API honored your supplied profile_id, or expect every cross-portfolio request to return 403. Use a key created in the target portfolio for portfolio-specific reads and reconciliation.
DELETE /orders?profile_id=<another portfolio> still targets the key’s bound portfolio. It can cancel eligible orders there, or return no canceled orders if none qualify. This applies with isolation off, with a portfolio-scoped key, and with cross portfolio access. Use a key created in the portfolio whose orders you intend to cancel.

​
Example

An account has three portfolios: Default, Client A, and Client B. Isolation is on. Each client has its own portfolio-scoped key. The operations team has a key in Default with cross portfolio access. Requests have the required permissions and valid parameters.

​
Enable or disable portfolio isolation

  1. Sign in to Coinbase Exchange.
  2. Open your profile menu and select Settings.
  3. Select Security.
  4. Turn on Portfolio isolation.
  5. In the Enable portfolio isolation? dialog, under Keep Cross Portfolio Access, select the keys that need it. Search by name, key, or portfolio, or click Select all. Click Clear to deselect every key.
  6. Click Continue and confirm with 2-step verification.
Keys you don’t select become portfolio-scoped immediately. The enablement dialog is the only time you can add cross portfolio access to an existing key. After isolation is on, you can only set it when you create a new key. To turn isolation off, return to Settings > Security and switch it off. Keys return to each endpoint’s existing behavior, including account-wide access where supported. Disabling isolation does not make the endpoints above honor another portfolio’s profile_id.
Before enabling isolation, test the endpoints your integrations use with portfolio-scoped and cross portfolio access keys. Check returned portfolio data as well as status codes: integrations can receive narrower results, 403, or 404, depending on the endpoint. Select cross portfolio access for keys that need to retain existing account-wide access.

​
Create a key with cross portfolio access

While isolation is on, you can set cross portfolio access when you create a key. New keys are portfolio-scoped unless you select it. To set it on an existing key, use the enablement dialog described in Enable or disable portfolio isolation.
  1. Sign in to Coinbase Exchange.
  2. Select API in the left navigation.
  3. Click New API Key.
  4. Under Permissions, select Cross Portfolio Access along with any View, Trade, Transfer, or Manage permissions the key needs.
  5. Create the key and save the key, secret, and passphrase.
Keys with cross portfolio access show Cross Portfolio Access under Permissions in My API Keys. Outside the enablement dialog, you can’t change this setting on an existing key. To remove it, delete the key and create a portfolio-scoped one.
Cross portfolio access preserves existing endpoint-specific access when isolation is on. View, Transfer, Trade, and Manage control what a key can do. Cross portfolio access does not grant these permissions: a key with View only cannot place or cancel orders. See API Key Permissions.

​
Recommendations

  • Give each client, desk, or strategy its own portfolio and a portfolio-scoped key.
  • Use a key created in each target portfolio for portfolio-specific reconciliation and order cancellation; do not rely on profile_id to switch a key’s portfolio.
  • Grant cross portfolio access only to operations, treasury, or reporting keys.
  • Review keys with cross portfolio access regularly and delete ones no longer needed.
  • Delete a client’s or team member’s keys when they leave.