token_wrong_kind: The browser token is for another surface

Each browser surface takes its own kind of token: a widget token (dx1.wgt.…) for the widget routes under /widgets/v1/, a budget-link token (dx1.blk.…) for /b/{token}, a portal token (dx1.ptl.…) for /portal/{token} and its freeze and revoke forms, and a top-up token (dx1.top.…) for /pay/topup/{token}. The kind is bound into the token's signature, so a well-formed token of one kind is refused on every other surface. For example, a widget token pasted into a portal link answers this code.

On the multi-tenant hosted tier the front door checks the kind before the request reaches the account's core, and answers a token of the wrong kind with token_malformed instead.

What to do

On the wire

HTTP 401, error type authentication_error. The widget routes always answer JSON; the budget link, portal and top-up pages answer a short HTML page naming the code, or JSON to a client that sends Accept: application/json (and not text/html):

{
  "error": "unauthorized",
  "errorDetail": {
    "type": "authentication_error",
    "code": "token_wrong_kind",
    "message": "this token is for another surface",
    "param": null,
    "doc_url": "…/developers/widgets.md#token-wrong-kind",
    "fix": "each surface takes its own token kind; mint the right one"
  }
}

The top-up page points doc_url at the top-up guide instead. See all error codes.