API keys
The keys you hold depend on who trades. An API trader holds one API key. A Gateway client holds an organization API key and a signer key.
Every key is an EC P-256 key pair. You keep the private half, and only the public half ever reaches us.
What each key does
A key signs one of two things:
- A sign-in challenge. You sign it to mint a token, and the token authenticates your calls. Authentication shows the call.
- A payload. An order or transfer returns unsigned payloads, and nothing moves until you sign them and execute.
| Key | Who holds it | Where it comes from | Signs |
|---|---|---|---|
| API key | an API trader | app.truemarkets.co | the sign-in challenge and your own payloads |
| organization API key | a Gateway client | the developer console | the sign-in challenge only |
| signer key | a Gateway client | you generate it | your users' payloads |
An API trader's key does both jobs because the app registers its public half on your account and on your wallet.
A Gateway client needs two keys because the jobs belong to different owners. The organization key signs in as your business. The signer key is registered on each user when you create them, and there's no way to rotate it yet. Signer keys covers where to keep it.
How each key signs
Signing in and signing a wallet transaction use different formats. Each product has a walkthrough with a diagram and runnable code: Gateway for an organization's two keys, and Trading API for an individual's one key.
Protect your keys
Anyone with your private key can mint tokens as you and sign from every wallet the key is registered on.
- Keep key files out of your repo and out of chat tools.
- If a key leaks, revoke it where you created it, at app.truemarkets.co or on the developer console's API keys page, and create a new one. Tokens it already minted keep working until they expire.
- If you lose a signer key, the wallets it's registered on can never sign again, and we can't recover them. Keep it in an HSM or a secrets manager, with a backup.
- A signer key registered on many users can sign for all of them. Guard it the way you guard a production database credential.
- Mint tokens from the key when you need them, rather than storing tokens long term.
Next: Authentication