Authentication

Use this guide to register a signer, manage API keys, and authenticate your API requests.

Overview

OBSDN auth has three pieces, each with a different job:

1. Sender wallet — owns your funds. You sign with it for actions that move funds (withdraw, transfer) or register an order signer. Verified on-chain by the Obsdn contract.
2. Signer wallet — a separate wallet authorized to place orders for the sender. Verified on-chain by the Obsdn contract at settlement.
3. API key pair — api_key + api_secret. Used to sign every API request so the backend knows the caller is you. Verified off-chain by the OBSDN backend; has no on-chain effect.

You register a signer once via POST /auth/signers; that call returns your first API key. Additional keys come from POST /auth/api-keys.

Register a Signer

Both the sender wallet and the signer wallet sign EIP-712 typed data, then a single call posts both signatures together. The response includes the first API key pair.

See the Register Signer reference for the request schema, Getting Started for an end-to-end curl example, and the Signing Guide for the EIP-712 payloads.

The response (under data) returns the first API key pair:

{
  "api_key": {
    "api_key": "obsdn_abc123...",
    "api_secret": "secret_xyz789...",
    "nm": "My Trading Bot",
    "sndr": "0x1234...",
    "signer": "0xabcd...",
    "crt_ts": "1734000000000000000",
    "exp_ts": "1735000000000000000",
    "is_ro": false
  }
}

exp_ts is "0" for keys with no expiration; otherwise a Unix nanoseconds timestamp.

Authenticating REST Requests

Every protected REST endpoint requires three headers:

The HMAC prehash concatenates the timestamp, the uppercase HTTP method, the URL path (no scheme, host, or query string), and the raw request body. Use the API secret as the HMAC key — the secret itself is never sent over the wire.

Requests are rejected with 401 if the timestamp is more than 5 seconds off the server clock, so regenerate the signature for every call.

Example

TS=$(date +%s)
METHOD=GET
URL_PATH=/portfolio
BODY=""
SIG=$(printf '%s%s%s%s' "$TS" "$METHOD" "$URL_PATH" "$BODY" \
  | openssl dgst -sha256 -hmac "$API_SECRET" -binary \
  | base64)

curl "https://api.obsdn.trade$URL_PATH" \
  -H "x-api-key: $API_KEY" \
  -H "x-api-timestamp: $TS" \
  -H "x-api-signature: $SIG"

For requests with a JSON body, pre-serialize the body once and reuse the same string in both the prehash and the request — whitespace or key-order differences between the signed and sent bytes will invalidate the signature.

Authenticating WebSocket

Private WebSocket channels (order, position, portfolio) require an auth message before subscription. The signature uses the same api_key / api_secret, but the prehash is ${api_key},${timestamp} and the timestamp window is ±60 seconds.

See WebSocket Overview for the full recipe.

API Key Lifecycle

All three endpoints below require the HMAC headers from Authenticating REST Requests.

Create

POST /auth/api-keys

{
  "nm": "Read-Only Dashboard",
  "is_ro": true
}

Both fields are optional; is_ro defaults to false. The response shape matches POST /auth/signers — { "api_key": { ... } } with a fresh api_key and api_secret. Save the secret immediately; it is shown only once. See the Create API Key reference.

Read-Only Keys

Set is_ro: true to issue keys that can read data but cannot:

• Place or cancel orders
• Modify positions or leverage
• Transfer or withdraw funds

Use read-only keys for dashboards, analytics, and monitoring jobs.

List

GET /auth/api-keys

Returns all API keys for the authenticated account. The api_secret field is empty on every entry — secrets are only returned at creation time. See the List API Keys reference.

Delete

DELETE /auth/api-keys

{
  "api_keys": ["obsdn_abc123", "obsdn_def456"]
}

Deletion is immediate and irrevocable — the keys can no longer authenticate any request. See the Delete API Keys reference.

Security Notes

1. Use separate signer wallets. If the signer key leaks, only signing authority is exposed — funds remain controlled by the sender wallet, which can revoke the signer.
2. Create read-only keys for monitoring. Limit exposure for dashboards and analytics jobs.
3. Rotate keys. Delete stale keys with DELETE /auth/api-keys and create new ones.
4. Store secrets securely. Use environment variables or a secret manager — never commit secrets, never log them.

Error Codes

Next Steps

• Place your first order
• View your portfolio
• Connect via WebSocket