Authentication

Building an app that acts for other STX members? See ISV.

The client needs your API key ID and its Ed25519 private key, as a path to the PEM file or as the PEM text. Creating a key, how requests are signed, and why a signature fails are covered on Authentication.

There are three ways to hand the key to the client. When more than one is set, constructor options win over environment variables, and environment variables win over the profile.

A credentials profile

Add a profile to ~/.stx/credentials:

[default]
region   = us
env      = demo
key_id   = your-key-id
key_file = ~/.stx/stx-key.pem

region and env pick the exchange; the values for each are listed under Environments. new STX() with no profile reads STX_PROFILE, then the [default] section, so the examples in this guide work as written:

import { STX } from "@stxapp/stx-typescript";

const client = new STX();

An API key works on one exchange only. To keep keys for more than one, add a section per key under any name you like, and pick one with profile:

const client = new STX({ profile: "my-demo" });

Environment variables

export STX_REGION=us STX_ENV=demo
export STX_KEY_ID=your-key-id
export STX_PRIVATE_KEY=~/.stx/stx-key.pem   # a path, or the PEM text

const client = new STX();

STX_HOST, STX_PROFILE and STX_CREDENTIALS (the path of the credentials file) are also read.

Constructor options

import { Environments, STX } from "@stxapp/stx-typescript";

const client = new STX({
  environment: Environments.USDemo,
  keyId: process.env.MY_KEY_ID,
  privateKey: process.env.MY_KEY_PEM, // a path, PEM text, bytes, or a KeyObject
});

If the key lives in an HSM or KMS, pass signer: async (message) => signature instead of privateKey; it returns the raw 64-byte Ed25519 signature.

Check it works

const me = await client.me();
console.log(me.user_id, me.scope); // scope: "read_only" or "read_write"

A bad key, or a machine clock that has drifted, throws STXAuthenticationException.