A challenge for a passkey ceremony: sign-in or registration (F-028). No bearer: it reveals no ledger fact.

POST

/v1/auth/challenge

const url = 'https://example.com/v1/auth/challenge';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"identity":"example","purpose":"authenticate"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/auth/challenge \
  --header 'Content-Type: application/json' \
  --data '{ "identity": "example", "purpose": "authenticate" }'

Request Body^required

application/json

POST /v1/auth/challenge (F-028).

object

identity

For register only, optional: the identity whose set the credential will join, did:aledgent:id:…. A registration over the challenge is then refused with ERR-CredentialInvalid for any other identity’s set (amendment 0027). Absent, the challenge is bound to no identity.

string | null

purpose

required

One of:

string
string

A sign-in: navigator.credentials.get.

string

Allowed value: authenticate

A registration: navigator.credentials.create.

string

Allowed value: register

Responses

200

A challenge, valid until expires_at, for one ceremony; a register challenge that names an identity serves that identity’s set only.

application/json

A challenge (F-028): pass challenge, decoded, as the ceremony’s challenge.

object

challenge

required

The challenge, base64url.

string

expires_at

required

When it expires.

integer format: uint64

Example^generated

{
  "challenge": "example",
  "expires_at": 1
}

4XX

Refused, with the named condition. The status is the alternative’s x-http-status.

application/json

One of:

ERR-NotAuthorised

object

description

required

Allowed value: The initiating principal holds no authority that covers this operation, account, asset or bound

error

required

Allowed value: ERR-NotAuthorised

Example

{
  "description": "The initiating principal holds no authority that covers this operation, account, asset or bound",
  "error": "ERR-NotAuthorised"
}

5XX

Refused, with the named condition. The status is the alternative’s x-http-status.

application/json

One of:

ERR-NotAuthorised

object

description

required

Allowed value: The initiating principal holds no authority that covers this operation, account, asset or bound

error

required

Allowed value: ERR-NotAuthorised

Example

{
  "description": "The initiating principal holds no authority that covers this operation, account, asset or bound",
  "error": "ERR-NotAuthorised"
}

Headers

Retry-After

integer

On ERR-DecisionUnavailable (503): seconds to wait before retrying with the same client key (DEC-27 (g)).

A challenge for a passkey ceremony: sign-in or registration (F-028). No bearer: it reveals no ledger fact.

Request Bodyrequired

Responses

200

Examplegenerated

4XX

Example

5XX

Example

Headers

Request Body^required

Example^generated