Running the examples¶

Every request example in this documentation reads the host and your credentials from three environment variables. Set them once in your shell and the examples run as written — copy, paste, done.

Variable	Holds	Example value
`TAPI_HOST`	Host of the environment you are calling, with no path	`https://api-sandboxdash.norcapsecurities.com`
`TAPI_CLIENT_ID`	Your Client ID	`NC00000`
`TAPI_API_KEY`	Your API key — a secret	—

1. Get your credentials¶

Sign in to the Transact Portal and open the Administrative tab. Your Client ID and API key are listed there. If you do not have sandbox access yet, see Getting Started.

2. Pick a host¶

Environment	`TAPI_HOST`
Sandbox	`https://api-sandboxdash.norcapsecurities.com`
Production	`https://api.norcapsecurities.com`

Sandbox and production are separate systems with separate credentials. A sandbox key will not authenticate against production. Build and test against sandbox; see Obtaining Production Keys when you are ready to go live.

3. Set the variables¶

macOS / LinuxWindows (PowerShell)

export TAPI_HOST=https://api-sandboxdash.norcapsecurities.com
export TAPI_CLIENT_ID=NC00000
printf 'API key: ' && read -rs TAPI_API_KEY && export TAPI_API_KEY

read -rs takes the key without echoing it to the terminal and without recording it in your shell history. Add the two export lines to ~/.zshrc or ~/.bashrc to make them permanent; keep the key itself out of those files and out of source control.

$env:TAPI_HOST = "https://api-sandboxdash.norcapsecurities.com"
$env:TAPI_CLIENT_ID = "NC00000"
$env:TAPI_API_KEY = Read-Host "API key"

These last for the current PowerShell session, and work in both Windows PowerShell 5.1 and PowerShell 7. Read-Host echoes what you type; add -MaskInput on PowerShell 7.1 or later to hide it.

The curl examples in this documentation are written for a POSIX shell. The simplest way to run them on Windows is from Git Bash or WSL, using the macOS / Linux commands above. To run one in PowerShell instead, call curl.exe, replace every $TAPI_HOST, $TAPI_CLIENT_ID and $TAPI_API_KEY with $env:TAPI_HOST, $env:TAPI_CLIENT_ID and $env:TAPI_API_KEY, and replace each trailing \ with a backtick (`).

4. Confirm it works¶

curl -X GET "$TAPI_HOST/v3/ping" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY"

{
  "status": "ok"
}

Anything else means the credentials or the host are wrong. "statusCode": "103" is an invalid or mismatched API key — the most common cause is a sandbox key sent to the production host, or the reverse. Other codes are listed in Error Codes.

Using a `.env` file in your own code¶

For the code you write, rather than for pasted examples, the same three variables usually come from a .env file:

TAPI_HOST=https://api-sandboxdash.norcapsecurities.com
TAPI_CLIENT_ID=NC00000
TAPI_API_KEY=your-api-key

Most runtimes read it through a library — dotenv for Node.js and Python, vlucas/phpdotenv for PHP. A .env file does not set your shell's environment, so the curl examples above will not pick it up; to load it into a shell as well, run set -a && . ./.env && set +a.

Add .env to your .gitignore before you put a key in it.

How the examples are written¶

Credentials travel in the Authorization header, as your Client ID and API key separated by a colon:

Authorization: Bearer {clientID}:{apiKey}

So a POST example carries only business parameters:

curl -X POST "$TAPI_HOST/v3/getLink" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d id=679

POST, PUT, PATCH and DELETE also accept clientID and developerAPIKey as body parameters, which is how older integrations authenticate and which continues to work. GET has no body, so send its credentials in the header. Use the header everywhere — it keeps credentials out of request bodies and URLs, which end up in tickets and logs. See Authorization Headers for the full rules and for examples in other languages.

Keeping your API key secret¶

The API key authorizes every action your integration can take. Treat it like a password.

Read it from the environment or a secrets manager. Never commit it, and never paste it into a ticket, a chat message or a screenshot.
Redact it from logs. Log the Client ID if you need to correlate requests; never the key.
Sandbox and production keys are separate. A leaked sandbox key is not a leak of production, but rotate both the same way.
If a key may have been exposed, contact techsupport@northcapital.com to have it rotated.