Exchange an identity proof

POST

/exchange

const url = 'https://auth.example.invalid/exchange';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"idpToken":"example","owner":"example","actor":"example","actorToken":"example","ttlSec":1,"view":"channel-writer","managerInstanceId":"example","sessionGrant":{"sessionId":"example","endpoint":"example","serving":{"instanceId":"example","epoch":1},"sig":"example","v":1,"space":"example","subjects":{"in":"example","out":"example"},"holder":{"id":"example","lifecycleUid":"example","processEpoch":1},"window":1,"iat":1,"nbf":1,"exp":1,"nonce":"example","issuer":{"keyId":"example"}},"transferWriter":{"instanceId":"example","hex":"example"}}'
};

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://auth.example.invalid/exchange \
  --header 'Content-Type: application/json' \
  --data '{ "idpToken": "example", "owner": "example", "actor": "example", "actorToken": "example", "ttlSec": 1, "view": "channel-writer", "managerInstanceId": "example", "sessionGrant": { "sessionId": "example", "endpoint": "example", "serving": { "instanceId": "example", "epoch": 1 }, "sig": "example", "v": 1, "space": "example", "subjects": { "in": "example", "out": "example" }, "holder": { "id": "example", "lifecycleUid": "example", "processEpoch": 1 }, "window": 1, "iat": 1, "nbf": 1, "exp": 1, "nonce": "example", "issuer": { "keyId": "example" } }, "transferWriter": { "instanceId": "example", "hex": "example" } }'

No loopback capability on this listener. Fresh pinned-issuer/audience IdP proof or managed ledger actor secret authorizes the selected actor. A successful human exchange includes the current grant the issuer authorized; a managed-agent exchange keeps the token, owner and exp response. Public views are channel-writer, channel-purger, manager-caller, session-caller and transfer-writer; other views return 403. ttlSec is constrained by issuer policy and proof expiry; agent bearer cap is 300 seconds. Invalid proof or manager selection returns 401. Refused proof/view attempts share the public peer budget; successful credentials still mint when the budget is full. Origin is refused.

Request Body^required

UTF-8 JSON; maximum 65536 bytes. An Authorization header does not replace the JSON proof.

application/json

One of:

object
object

Provide idpToken for a human OR owner plus actorToken for a managed agent, never both. Agent view may only be manager-caller. managerInstanceId requires manager-caller; sessionGrant accompanies session-caller; transferWriter accompanies transfer-writer. Native SessionGrant is verified against the redeemed session ledger; the nested schema documents its transport shape only.

object

idpToken

required

string

>= 1 characters

owner

string

>= 1 characters

actor

string

>= 1 characters

actorToken

string

>= 1 characters

ttlSec

number

view

string

Allowed values: channel-writer channel-purger manager-caller session-caller transfer-writer

managerInstanceId

string

sessionGrant

Transport envelope only. Nested native fields and operation-specific constraints are defined by SessionGrant in the linked source; this schema is not a complete native command contract.

object

sessionId

string

>= 1 characters

endpoint

string

>= 1 characters

serving

object

instanceId

required

string

>= 1 characters

epoch

required

integer

sig

string

>= 1 characters

Allowed value: 1

space

string

>= 1 characters

subjects

object

required

string

>= 1 characters

out

required

string

>= 1 characters

holder

object

required

string

>= 1 characters

lifecycleUid

required

string

>= 1 characters

processEpoch

required

integer

window

integer

iat

integer

nbf

integer

exp

integer

nonce

string

>= 1 characters

issuer

object

keyId

required

string

>= 1 characters

transferWriter

object

instanceId

required

string

>= 1 characters

hex

required

string

>= 1 characters

Responses

200

Successful response.

application/json

object

token

required

string

>= 1 characters

owner

required

string

>= 1 characters

exp

required

integer

grant

Current issuer-authorized agent grant. Present for a human IdP exchange and absent for a managed-agent secret exchange.

object

scope

required

Array<string>

allowSubscribe

required

Array<string>

allowPublish

required

Array<string>

dmHistory

required

Allowed value: own

Example

{
  "grant": {
    "dmHistory": "own"
  }
}

400

JSON error. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413. An unexpected failure is 400 unless a route handles it separately.

application/json

object

error

required

string

code

string

outcome

string

Allowed values: not-executed executed unknown

Example

{
  "outcome": "not-executed"
}

401

JSON error. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413. An unexpected failure is 400 unless a route handles it separately.

application/json

object

error

required

string

code

string

outcome

string

Allowed values: not-executed executed unknown

Example

{
  "outcome": "not-executed"
}

403

JSON error. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413. An unexpected failure is 400 unless a route handles it separately.

application/json

object

error

required

string

code

string

outcome

string

Allowed values: not-executed executed unknown

Example

{
  "outcome": "not-executed"
}

405

JSON error. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413. An unexpected failure is 400 unless a route handles it separately.

application/json

object

error

required

string

code

string

outcome

string

Allowed values: not-executed executed unknown

Example

{
  "outcome": "not-executed"
}

413

JSON error. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413. An unexpected failure is 400 unless a route handles it separately.

application/json

object

error

required

string

code

string

outcome

string

Allowed values: not-executed executed unknown

Example

{
  "outcome": "not-executed"
}

415

JSON error. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413. An unexpected failure is 400 unless a route handles it separately.

application/json

object

error

required

string

code

string

outcome

string

Allowed values: not-executed executed unknown

Example

{
  "outcome": "not-executed"
}

429

JSON error. Route guards run before proof evaluation; parser failures are 400 and byte overflow is 413. An unexpected failure is 400 unless a route handles it separately.

application/json

object

error

required

string

code

string

outcome

string

Allowed values: not-executed executed unknown

Example

{
  "outcome": "not-executed"
}

503

Public admission cap (64 in flight), 10 second request deadline, or a route-specific unavailable read/effect. A service authority 503 may follow a binding; retain the request identity.

application/json

object

error

required

string

code

string

outcome

string

Allowed values: not-executed executed unknown

Example

{
  "outcome": "not-executed"
}

Exchange an identity proof

Request Bodyrequired

Responses

200

Example

400

Example

401

Example

403

Example

405

Example

413

Example

415

Example

429

Example

503

Example

Request Body^required