API authentication

For background on authing, see Authentication and authorization.

Below, replace <NETWORK> with mainnet, ropsten, or rinkeby.

You can observe authentication in action using the browser's inspector while authenticating into Mainnet .

Request authentication challenge

This is the first step when authenticating.

URL: https://zone-manager.<NETWORK>.kchannels.io/authentication_api/

REQUEST (HTTP GET)

  • Query params:

    • signing_identity -- Ethereum address of client (claimed)

    • client_unpredictable_number -- large (64-bit) random number generated by the client to guard against replay attacks

RESPONSE

  • Headers:

    • Content-Type: application/json

  • Body:

    • The backend returns an AuthenticationChallenge object.

Next steps

  1. Sign the authentication challenge using EIP-712 and add the signature to the object (in a new field called signature)

  2. Submit the signed authentication challenge, as follows:

Submit signed authentication challenge

This is the second step when authenticating. Successful authentication results in a JWT token that the client should submit with every subsequent request.

URL: https://zone-manager.<NETWORK>.kchannels.io/authentication_api/

REQUEST (HTTP POST)

  • Headers:

    • Content-Type: application/x-www-form-urlencoded; charset=UTF-8

  • Body:

    • Form URL-encoded response to authentication challenge:

      • text

      • client_unpredictable_number

      • unpredictable_number

      • client_ip

      • issued_at

      • expires_at

      • signing_identity

      • issuer_signature

      • signature

RESPONSE

  • Headers:

    • Content-Type: application/json

  • Body:

    • The backend returns an AuthenticationSuccess object.

Next steps

  1. Extract and save the JWT token, which is valid for 24 hours.

  2. Add the header Authorization: Bearer YOUR_JWT_TOKEN to every subsequent request you make.

  3. When the token expires, the backend returns HTTP 401. Use the same authentication flow to obtain a new token.