Authentication

Time Seventeen authentication is layered. Each layer answers a different question, and a request may need to satisfy several of them at once.

Trust layers

1. Public market/index/reference reads — no identity requirement unless operational policy later configures one. Covers index, market, price, rating, and severity discovery/history endpoints.
2. API credential request authentication — key ID + canonical request signature + timestamp + nonce, required for all private account/trading endpoints.
3. Wallet/account binding — an EIP-712 T17ApiAuthorization proving control of a signer and delegating defined scopes to an API credential.
4. Order authorization — every order is independently EIP-712 signed as a T17Order, even when the surrounding HTTP request is already API-authenticated.

API keys

API keys have explicit environments (for example sandbox, production — both remain production configuration placeholders in Draft v0.1) and explicit scopes:

Key lifecycle — creation, listing, rotation, revocation, and audit logging — is documented as a contract, not as a claim that a live self-service endpoint exists yet:

POST   /account/api-keys              create a scoped key for an environment
GET    /account/api-keys              list keys (never returns the secret again)
POST   /account/api-keys/{key_id}/rotate
POST   /account/api-keys/{key_id}/revoke
GET    /account/api-keys/{key_id}/audit-log

Keys MAY be restricted to an IP/network allowlist where an account’s operational policy requires it. A key’s secret is shown exactly once at creation time and must be stored in an approved secret manager — never in source control, logs, or client-side JavaScript.

Canonical request signing

Every private REST request carries these headers:

T17-Access-Key: <key-id>
T17-Access-Timestamp: <unix-ms>
T17-Access-Nonce: <unique-nonce>
T17-Access-Signature: <encoded-signature>
T17-Access-Signature-Version: v1

The signed canonical request is built from: HTTP method, normalized path, canonically sorted query string, a SHA-256 hash of the request body, the timestamp, the nonce, the key ID, and the environment/audience. The server rejects replay of a previously accepted (key_id, nonce) pair. Exact clock-skew tolerance and nonce-retention window are production configuration, not fixed by Draft v0.1.

T17-Access-Signature-Version=v1
method=POST
path=/v1/orders
query=
body_sha256=<sha256-hex-of-request-body>
timestamp=1788350400000
nonce=n_demo_9f21c3
key_id=key_demo_001
environment=sandbox

{
  "outcome_id": "out_demo_001",
  "side": "BUY",
  "price": "0.6400",
  "quantity": "150.00",
  "time_in_force": "GTC"
}

EIP-712 account authorization

T17ApiAuthorization is a wallet-signed typed-data message that binds an owner and signer to an account and delegates scopes to a specific API key:

Domain separation includes the protocol name, major version, chain ID when applicable, a verifying contract when one is deployed, or a production-approved salt/audience when verification happens off-chain.

{
  "name": "TimeSeventeen",
  "version": "1",
  "chainId": "YOUR_APPROVED_CHAIN_ID",
  "verifyingContract": "YOUR_APPROVED_VERIFYING_CONTRACT",
  "salt": "YOUR_APPROVED_DOMAIN_SALT"
}

EIP-712 order authorization

Every order is independently signed as a T17Order typed-data message, regardless of the request-level API signature:

The transport body MAY add non-authorizing metadata (for example a client tag), but any field that can change the order’s economic effect MUST be part of the signed payload.

EOA vs. smart-account signatures

EOA (externally owned account) and smart-account/ERC-1271-style signatures are declared through distinct signature_type values rather than being inferred from the signature bytes. Draft v0.1 does not fix which smart-account standard is approved, nor a production chain ID or verifying contract — those remain configuration placeholders.

Replay prevention summary

Where to go next

• Getting Started → Authentication preparation for safe credential-handling guidance before you integrate.
• Orders for how request authentication and order authorization combine in the validation pipeline.
• Errors for the AUTH_*, SIGNATURE_*, and REPLAY_* error families.