Authentication

The gateway authenticates requests with API keys. You get a key by proving control of a Stellar wallet: request a challenge, sign it with the wallet, and exchange the signed proof for a keyId and secret pair. This page covers the full flow, the exact request and response shapes, the headers every authenticated call needs, and key management.

Base URL for all examples: https://noether-api.proudmeadow-533cf0d8.germanywestcentral.azurecontainerapps.io.

What a key looks like

The secret is shown once, in the issuance response. The gateway stores only a peppered SHA-256 hash of it, so a lost secret cannot be recovered: revoke the key and mint a new one instead.

Check beta status

Public, no auth required. Pass your address to see whether you can mint a key:

curl -s "https://noether-api.proudmeadow-533cf0d8.germanywestcentral.azurecontainerapps.io/v1/keys/beta-status?address=GBTRADER..."

{ "gated": true, "allowed": false }

• gated is true when an allowlist is configured (it is, on the current deployment).
• allowed is true when issuance is open to everyone or when the supplied address is on the list. Without an address parameter, allowed is false whenever the gate is on.

Getting a key

curl -s -X POST https://noether-api.proudmeadow-533cf0d8.germanywestcentral.azurecontainerapps.io/v1/keys/challenge \
  -H "content-type: application/json" \
  -d '{"address":"GBTRADER..."}'

{ "challengeHex": "e1e7d001291a9253c8052fe6dda16e64d4b890b092044d56bcf0430d81366bc3", "expiresAt": 1789683629127 }

// sign-challenge.ts: build and sign the placeholder transaction
import {
  Account, Keypair, Operation, TransactionBuilder,
} from '@stellar/stellar-sdk';

const NETWORK_PASSPHRASE = 'Test SDF Network ; September 2015';

function signChallenge(challengeHex: string, keypair: Keypair): string {
  const placeholder = Keypair.random().publicKey(); // dummy source account
  const account = new Account(placeholder, '0');    // sequence 0
  const tx = new TransactionBuilder(account, {
    fee: '0',
    networkPassphrase: NETWORK_PASSPHRASE,
  })
    .addOperation(Operation.manageData({
      name: 'noether-api auth',
      value: Buffer.from(challengeHex, 'hex'),      // the 32 challenge bytes
      source: keypair.publicKey(),                  // your address
    }))
    .setTimeout(0)
    .build();
  tx.sign(keypair);
  return tx.toXDR(); // base64 signed-transaction XDR
}

curl -s -X POST https://noether-api.proudmeadow-533cf0d8.germanywestcentral.azurecontainerapps.io/v1/keys \
  -H "content-type: application/json" \
  -d '{
    "address": "GBTRADER...",
    "challenge": "e1e7d001...the challengeHex...",
    "signature": "AAAAAgAAA...base64-signed-tx-XDR...",
    "label": "trading-bot"
  }'

{
  "keyId": "nk_3f9a1c0b8d2e4f6a7b8c9d0e",
  "secret": "64-hex-char-secret...",
  "tier": "standard",
  "owner": "GBTRADER...",
  "createdAt": 1789683600000
}

curl -s https://noether-api.proudmeadow-533cf0d8.germanywestcentral.azurecontainerapps.io/v1/account/me \
  -H "Authorization: Bearer nk_3f9a1c0b8d2e4f6a7b8c9d0e:64-hex-char-secret..." \
  -H "X-Timestamp: $(date +%s)"

{ "owner": "GBTRADER...", "tier": "standard", "keyId": "nk_3f9a1c0b8d2e4f6a7b8c9d0e" }

The X-Timestamp header

X-Timestamp is required replay protection on every authenticated REST request. The value must be the current unix time in seconds, within 30 seconds either side of the gateway's clock. A missing header fails with 401 missing_timestamp and a value outside the window fails with 401 stale_timestamp, both before the key itself is checked. The official SDKs send the header on every authenticated call.

Authentication errors

All auth failures are 401 with a small JSON body:

Authenticated requests are rate-limited per owning wallet at 600 requests per minute (standard tier), versus 60 requests per minute per IP without a key. The bearer key is resolved before the rate limiter runs, so attaching your key even to public endpoints moves you to the higher bucket. On breach you get 429 with a Retry-After header and body {"error":"rate_limited","retry_after_sec":12}.

Managing keys

List your keys

GET /v1/keys (requires auth) returns every key with the same owner as the authenticated key, newest first, including revoked ones:

curl -s https://noether-api.proudmeadow-533cf0d8.germanywestcentral.azurecontainerapps.io/v1/keys \
  -H "Authorization: Bearer nk_3f9a1c0b8d2e4f6a7b8c9d0e:64-hex-char-secret..." \
  -H "X-Timestamp: $(date +%s)"

{
  "keys": [
    {
      "keyId": "nk_3f9a1c0b8d2e4f6a7b8c9d0e",
      "owner": "GBTRADER...",
      "tier": "standard",
      "label": "trading-bot",
      "createdAt": 1789683600000,
      "lastUsedAt": 1789683900000,
      "revokedAt": null
    }
  ]
}

Timestamps are millisecond epochs; label, lastUsedAt and revokedAt may be null. lastUsedAt updates on every successful authentication. Secrets are never included.

Revoke a key

DELETE /v1/keys/{keyId} (requires auth). Any of your keys can revoke any key belonging to the same owner, including itself:

curl -s -X DELETE https://noether-api.proudmeadow-533cf0d8.germanywestcentral.azurecontainerapps.io/v1/keys/nk_3f9a1c0b8d2e4f6a7b8c9d0e \
  -H "Authorization: Bearer nk_othervalidkey000000000000:64-hex-char-secret..." \
  -H "X-Timestamp: $(date +%s)"

{ "revoked": true }

Revocation takes effect immediately: the revoked key fails auth on its next request. If the key does not exist, belongs to a different owner, or is already revoked, you get 404 with {"error":"key_not_found"}.

Let an SDK do it

Both SDKs wrap the whole flow in one call: client.issueKey(...) (or client.keys.create(...)) in the TypeScript SDK and await client.keys.create(...) in the Python SDK. You pass your address and a signer function; the SDK fetches the challenge, builds the placeholder transaction, has your signer sign its hash, and exchanges the result for a key. The closed-beta gate applies the same way.

Complete copy-paste flow

End to end with curl plus a small Node script for the signing step:

BASE=https://noether-api.proudmeadow-533cf0d8.germanywestcentral.azurecontainerapps.io
ADDRESS=GBTRADER...   # your Stellar public key

# 1. Check the beta gate
curl -s "$BASE/v1/keys/beta-status?address=$ADDRESS"

# 2. Request a challenge (valid five minutes, single use)
CHALLENGE=$(curl -s -X POST "$BASE/v1/keys/challenge" \
  -H "content-type: application/json" \
  -d "{\"address\":\"$ADDRESS\"}" | node -pe 'JSON.parse(require("fs").readFileSync(0)).challengeHex')

# 3. Sign it (a script wrapping the signChallenge function above with your keypair)
SIGNED_XDR=$(npx tsx sign-challenge.ts "$CHALLENGE")

# 4. Exchange it for a key; the secret in this response is shown once
curl -s -X POST "$BASE/v1/keys" \
  -H "content-type: application/json" \
  -d "{\"address\":\"$ADDRESS\",\"challenge\":\"$CHALLENGE\",\"signature\":\"$SIGNED_XDR\",\"label\":\"my-bot\"}"

# 5. Use it (substitute the keyId and secret from step 4)
curl -s "$BASE/v1/account/me" \
  -H "Authorization: Bearer nk_yourkeyid:yoursecret" \
  -H "X-Timestamp: $(date +%s)"

Endpoint summary

Next steps

• REST API: every endpoint, including the prepare, sign, submit trading flow
• WebSocket API: the login op uses this same key pair for private channels
• TypeScript SDK and Python SDK: handle the challenge flow and send X-Timestamp for you
• Generated reference: try endpoints interactively
• Errors: the full error taxonomy