Authentication and Authority

Aura separates three concerns:

Credential	Identifies	Can authorize user assets?
None	Anonymous public client	No
Developer key	Builder, environment, scopes and quota	No
Wallet session	A wallet that signed a one-time challenge	Only for session-bound endpoints; it cannot authorize restricted trading by itself
Restricted trading authorization	A user’s bounded consent grant for one builder	Only within its market/outcome, BUY/SELL, expiry and cap policy

Private account and private-webhook operations can require both a developer key and the matching wallet session. Restricted order requests instead require the developer key plus the user’s aura_trade_… authorization and do not require an unrelated session bearer. Supplying more scopes to a developer key never substitutes for user consent.

Developer keys

Send a developer key only in this header:

x-aura-developer-key: aura_dev_live_...

Never append it to a URL. URLs commonly appear in proxy, CDN, browser-history and analytics logs. Available scopes are:

public:read and market:read
realtime:public
account:read
transactions:read
trade:place and trade:cancel
webhooks:manage

Key creation is a wallet-session operation:

const { key, secret } = await aura.developerKeys.create({
  name: 'production-market-data',
  scopes: ['market:read', 'realtime:public'],
  expiresInDays: 30,
})

console.log(key.builderCode)

The secret is displayed once. Aura stores only its digest. Put the returned value directly in a server-side secret manager. Rotate it rather than copying it between developers, and revoke it when the integration is retired. key.builderCode is the immutable public attribution identity bound to the key owner. It is not secret and grants no authority. For a trading integration, give the user this exact code when they create restricted access in Aura’s first-party console and use a developer key with the required trade:* scopes; the order facade verifies that the authorization binding matches the presented key. Key rotation preserves the code.

Do not embed a privileged developer key in browser JavaScript. Anyone can extract it and consume its quota. Browser code should normally use public access plus the user’s HttpOnly session.

Establish a wallet session

Request a one-time challenge

curl -X POST https://api.aura.markets/v1/auth/challenge \
  -H 'content-type: application/json' \
  -d '{"address":"3Cef...your-wallet"}'

The challenge expires after five minutes and is single-use. Issuing it for a known address is preferred; an address-less challenge must be returned verbatim in the session request.

Sign the exact challenge text

Use the wallet’s signMessage operation with the Alephium message hasher. Do not ask for, export, or handle the wallet seed. Aura has no raw seed export flow.

`keyType`	Use
`gl-secp256k1`	Aura’s groupless embedded wallet
`default`	Standard grouped Alephium wallet tooling

Exchange the signature

curl -X POST https://api.aura.markets/v1/auth/session \
  -H 'content-type: application/json' \
  -c cookies.txt \
  -d '{
    "address":"3Cef...your-wallet",
    "publicKey":"0233...compressed-public-key",
    "signature":"abcd...raw-signature",
    "keyType":"gl-secp256k1"
  }'

The browser flow receives an HttpOnly aura_session cookie and a CSRF token in the response. Echo the CSRF token in x-csrf-token on session-owned mutations.

For non-JavaScript implementations, the signed digest is:

blake2b-256(utf8("Alephium Signed Message: " + exactChallengeText))

The signature is a 64-byte raw r || s secp256k1 signature encoded as lowercase hex. It is not DER and has no recovery byte. Browsers should keep the session in the HttpOnly cookie:

const aura = createAuraClient({
  baseUrl: 'https://api.aura.markets',
  session: { kind: 'cookie', credentials: 'include', csrfToken: () => csrf },
})

Backends may request issueToken: true when exchanging the challenge and send the returned token as:

Authorization: Bearer <user-session-token>

Bearer requests do not need CSRF because browsers do not attach an Authorization header automatically. Store the token like any other secret; never put it in a query string, application log or browser localStorage.

Compose builder and user credentials

const aura = createAuraClient({
  baseUrl: 'https://api.aura.markets',
  developerKey: () => secretManager.read('aura/developer-key'),
  session: { kind: 'bearer', token: () => userSessionStore.read(userId) },
})

const account = await aura.account.snapshot(userAddress)

The request carries both headers. Aura independently checks the key scope and that the path address belongs to the session.

Restricted trading authority

API trading uses a separate, user-created authorization held by Aura’s enclave. It is narrowly limited by account, environment, market/outcome permissions, BUY/SELL caps, expiry and builder attribution. The API signs and submits an authorized intent internally; intent signatures and cancel signatures are not returned to the builder. Users can inspect, rotate and revoke that authorization. Revoking a developer key stops the builder identity; revoking the user authorization stops its trading power. Treat these as independent controls. Creation, rotation and revocation deliberately remain in Aura’s signer iframe and first-party authorization console, where each high-authority action is bound to explicit user consent. The aura_trade_… secret is shown once and delivered to the builder the user selected. The builder must place it directly in a server-side secret store and send it only in x-aura-trading-authorization alongside its developer key. The builder API and @aura/builder-sdk cannot mint or broaden an authorization. Do not call wallet-svc or enclave internal routes. The first-party console keeps the same idempotency key when a create or rotation has an ambiguous transport failure. The authorization service never replays a show-once secret: if the write committed but the response was lost, the console reloads the resulting authorization ID and generation, then requires the user to rotate with a new idempotency key or revoke it. Reusing an idempotency key with different terms is a conflict. These recovery operations remain inside the passkey/action-bound console; there is no builder API route for them.

Manage active sessions

GET /v1/auth/sessions returns at most the 100 most recent sessions owned by the authenticated wallet. Rows contain only an opaque UUID, creation/last-seen and expiry timestamps, nullable revocation time, and current; Aura never returns the JWT, CSRF secret, token digest, or a credential fingerprint.

const { sessions } = await aura.auth.listSessions()

for (const session of sessions) {
  if (!session.current && session.revokedAt === null) {
    await aura.auth.revokeSession(session.id)
  }
}

Single-session revocation is intentionally enumeration-safe and idempotent: missing, already-revoked, and foreign UUIDs all return 204. Revoking the current session clears its cookie. revokeAllSessions() immediately invalidates every cookie and bearer token for that wallet, including the presented session. Cookie-authenticated logout and revocation are writes and require the current x-csrf-token. Bearer callers are CSRF-exempt. POST /v1/auth/logout revokes the exact presented session (so copied tokens stop working), clears browser cookies, and still returns 204 when no active session is present.

Session endpoints

Endpoint	Purpose
`POST /v1/auth/challenge`	Create a short-lived, one-time message to sign.
`POST /v1/auth/session`	Verify ownership and issue the cookie; optionally return a backend bearer token.
`GET /v1/auth/session`	Read the current cookie session and CSRF value.
`POST /v1/auth/logout`	Revoke the presented cookie/bearer session and clear cookies; cookie callers send CSRF.
`GET /v1/auth/sessions`	List safe metadata for sessions owned by the authenticated wallet.
`DELETE /v1/auth/sessions/{sessionId}`	Idempotently revoke one owned opaque session ID.
`DELETE /v1/auth/sessions`	Revoke every session for the authenticated wallet.

Raw seed export is deliberately unavailable. Deleting an Aura wallet account must use the dedicated account-destruction/recovery policy; it is not a way to reveal custody material.

Get Started

Guides

Reference

Endpoints

Realtime Stream

Authentication and Authority

Developer keys

Establish a wallet session

Compose builder and user credentials

Restricted trading authority

Manage active sessions

Session endpoints

​Developer keys

​Establish a wallet session

​Browser cookie versus backend bearer

​Compose builder and user credentials

​Restricted trading authority

​Manage active sessions

​Session endpoints

Developer keys

Establish a wallet session

Browser cookie versus backend bearer

Compose builder and user credentials

Restricted trading authority

Manage active sessions

Session endpoints