API Key Permissions¶

Each API key has two independent sets of permissions: legacy permissions and scopes. Which set applies depends on the style of endpoint being called. A request is checked against one set only, never both.

Endpoint style	Example	Permission system
Method-style	`POST /v3/getAccount`, `PUT /v3/createParty`, `POST /v3/updateTrade`	Legacy permissions
Resource-style	`GET /v3/parties`, `GET /v3/accounts/{accountId}`, `PATCH /v3/accounts/{accountId}`	Scopes

As a rule of thumb, an endpoint whose name is an operation such as get..., create..., update..., or delete... uses legacy permissions. An endpoint whose path names a resource uses scopes. See Endpoint Styles for more on the two styles.

Legacy Permissions¶

Legacy permissions control access to method-style endpoints. They are granted per method, and each method has a set of required parameters that must also be enabled for the key.

Legacy permissions do not affect resource-style endpoints, and they do not redact fields in responses.

When a legacy permission is missing, the API responds with HTTP 404 and one of these status codes:

`statusCode`	`statusDesc`	Meaning
`110`	Permission denied	The key can call the method but is missing one or more of its required parameters.
`111`	You are not authorized to invoke/use this method	The method is not enabled for the key. This code is also returned when the request comes from an IP address that is not on the client's allowlist.

Scopes¶

Scopes control access to resource-style endpoints. Each scope names a resource and an access level:

{resource}.read     # retrieve records
{resource}.write    # create or modify records

For example, party.read allows GET /v3/parties, and account.write allows PATCH /v3/accounts/{accountId}.

When a required scope is missing, the API responds with HTTP 403 and statusCode 1403.

PII Levels¶

Read scopes for resources that contain personal information carry a PII level. The level determines which fields are returned in full and which are returned as the literal string REDACTED.

Scope	Fields returned
`{resource}.read`	Base fields only: identifiers, statuses, and dates
`{resource}.read.pii_low`	Base fields, plus limited personal and financial details
`{resource}.read.pii_medium`	All of the above, plus names, contact details, and addresses
`{resource}.read.pii_high`	All fields, including government identifiers such as Social Security numbers and tax IDs

Each level includes everything below it. For the exact fields at each level, see Field Redaction by Scope.

Configuring Permissions¶

Both sets of permissions are managed per API key on the key's Assign Permission page in the Transact Portal. The page has a Scopes tab and a Legacy Permissions tab. If you do not have access to this page, contact North Capital support.

For a new integration, we recommend:

On the Legacy Permissions tab, select Grant all legacy permissions.
On the Scopes tab, grant read and write access only for the resources the integration uses.
Set each resource's PII level to the lowest level that meets the integration's needs. Reserve pii_high for workflows that require government identifiers, such as compliance or tax reporting.

Exceptions¶

createIssuerAccount and deleteIssuerAccount are method-style endpoints that also accept the issuer.write scope. A key with issuer.write can call them without the corresponding legacy permissions.