Authentication

Users (game players and Twitch streamers) authenticate themselves by using a Two-factor auth style PIN code. This code is generated on the server and displayed on the Twitch extension. The code is then entered into the game client, sent to the server for verification.

Generating a PIN

An extension with a valid twitch.tv JWT may send an authorized request to https://api.muxy.io/v1/e/gamelink/token to receive a token response in the form

{
    "token": "pZV4Se"
}

Note that this token is case sensitive.

Receiving Authentication Updates

When the client subscribes to "authentication" events:

{
  "action": "subscribe",
  "params": {
    "request_id": 234,
    "target": "authentication"
  }
}

The server will respond positively and begin sending auth updates:

{
  "meta": {
    "request_id": 234,
    "action": "subscribe",
    "target": "authentication",
    "timestamp": 1583777221501
  },

  "data": {
    "ok": true
  }
}

Or send a notification if an error occurs:

{
  "meta": {
    "request_id": 234,
    "action": "subscribe",
    "target": "authentication",
    "timestamp": 1583777221501
  },

  "errors": [
    {
      "status": 500,
      "title": "Internal Service Error",
      "detail": 
        "An internal error prevented the server from processing the request"
    }
  ]
}

Authenticating a User

Authentication is performed by using the authenticate action. This action is sent to the server along with either a user-entered PIN or a stored JWT refresh token to authenticate the user and allow access to other actions.

User-entered PIN

If the user has not been authenticated, send a user-entered 4-character PIN code that matches one displayed in the extension. If the code matches, the connection's access rights will be upgraded and a message will be sent with a signed JWT access token for use in future connections. If the code does not match, the connection's access rights will not change and an error message will be sent.

The returned JWT from this authentication process are issued for the specific user and their channel, with the 'broadcaster' role. These JWTs can be used with the Muxy HTTP API. These JWTs are valid for 30 days, but can be extended by using the refresh functionality, outlined below.

When the game client sends a user-entered PIN:

{
  "action": "authenticate",
  "params": {
    "request_id": 333
  },

  "data": {
    "pin": "pZV4Se",
    "client_id": "your-client-id"
  }
}

The server will respond with a storable JWT:

{
  "meta": {
    "request_id": 333,
    "action": "authenticate",
    "target": "",
    "timestamp": 1583777666077
  },

  "data": {
    "jwt": "eyJhbG..."
  }
}

Or a human-readable error message:

{
  "meta": {
    "request_id": 333,
    "action": "authenticate",
    "channel": "",
    "timestamp": 1583777666077
  },

  "errors": [
    {
      "status": 400,
      "title": "Bad Request",
      "detail": "The provided PIN is invalid or expired"
    }
  ]
}

Stored JWT Refresh Token

If your application has already authenticated the user and has a stored JWT, send the encoded token to verify and upgrade the connection's access rights. If the JWT is valid and signed, the server will send a message with a new "refreshed" token that can be used for future connections. If the JWT has expired or otherwise cannot be verified, an error message will be sent.

When the game client sends a stored JWT:

{
  "action": "authenticate",
  "params": {
    "request_id": 444
  },

  "data": {
    "jwt": "eyJhbG...",
    "client_id": "your-client-id"
  }
}

The server will respond with a refreshed JWT:

{
  "meta": {
    "request_id": 444,
    "action": "authenticate",
    "channel": "",
    "timestamp": 1583779685222
  },

  "data": {
    "jwt": "eyJhbG..."
  }
}

Or a human-readable error message:

{
  "meta": {
    "request_id": 444,
    "action": "authenticate",
    "channel": "",
    "timestamp": 1583779685222
  },

  "errors": [
    {
      "status": 400,
      "title": "Bad Request",
      "detail": "The provided JWT does not match any known account."
    }
  ]
}