DID Authentication

DID authentication

LayerX uses Decentralized Identifiers (DIDs) as account identities. Authentication is based on a challenge/verify flow using Ed25519 signatures - no passwords, no API keys, no shared secrets.

How it works

1. The agent calls the challenge endpoint with its DID.
2. The server returns a unique challenge string (nonce + timestamp).
3. The agent signs the challenge with its Ed25519 private key.
4. The agent submits the signed challenge to the verify endpoint.
5. The server returns a principal token - a short-lived bearer token for subsequent API calls.

Challenge endpoint

curl -X POST https://layerx.paxeer.network/v1/agent/auth/challenge \
  -H "Content-Type: application/json" \
  -d '{"did": "did:ed25519:agent.scanner.v1"}'

Response:

{
  "challenge": "a]3F9xK2m...base64url-encoded-nonce...",
  "expires_at": "2026-01-15T10:05:00Z"
}

The challenge expires after 5 minutes. If it expires before you verify, request a new one.

Verify endpoint

Sign the challenge string with your Ed25519 private key and submit the signature.

curl -X POST https://layerx.paxeer.network/v1/agent/auth/verify \
  -H "Content-Type: application/json" \
  -d '{
    "did": "did:ed25519:agent.scanner.v1",
    "challenge": "a]3F9xK2m...",
    "signature": "base64url-encoded-ed25519-signature"
  }'

Response:

{
  "principal_token": "eyJhbGciOiJFZERTQSJ9...",
  "expires_at": "2026-01-15T11:05:00Z"
}

Principal tokens

A principal token is a short-lived JWT signed by the LayerX server. It contains the agent's DID, issuance time, and expiry. Use it as a bearer token for all subsequent API calls.

Authorization: Bearer eyJhbGciOiJFZERTQSJ9...

Principal tokens expire after 1 hour by default. When a token expires, re-run the challenge/verify flow to obtain a new one.

Dual authorization

LayerX supports two authorization modes for transfer requests:

DID-signed intent

Sign the transfer payload directly with the agent's Ed25519 key. The sequencer verifies the signature against the DID's registered public key. This mode is used by SDKs and programmatic clients.

{
  "to": "did:ed25519:service.data.v2",
  "amount": "1.50",
  "did": "did:ed25519:agent.scanner.v1",
  "signature": "base64url-encoded-signature-over-payload"
}

Principal token

Include a valid principal token in the Authorization header. The sequencer verifies the token's signature and checks that the token's DID matches the transfer sender. This mode is used by interactive clients and web dashboards.

Both modes are accepted on all write endpoints. Choose the one that fits your integration pattern - they are mutually interchangeable.

DID resolution

LayerX resolves DIDs to Ed25519 public keys using the did:ed25519 method. The public key is registered when the account is first created (via deposit or wallet creation). The DID document is stored in the Postgres ledger and can be queried via the API.