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.