@spec token_get_from_code(
  TwitchAPI.Auth.t(),
  code :: String.t(),
  redirect_url :: String.t()
) ::
  {:ok, Req.Response.t()} | {:error, term()}

Get an access token with an authorization code.

https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#authorization-code-grant-flow

If the request succeeds, it returns an access token and refresh token.

{
  "access_token": "rfx2uswqe8l4g1mkagrvg5tv0ks3",
  "expires_in": 14124,
  "refresh_token": "5b93chm6hdve3mycz05zfzatkfdenfspp1h1ar2xxdalen01",
  "scope": [
    "channel:moderate",
    "chat:edit",
    "chat:read"
  ],
  "token_type": "bearer"
}copy

@spec token_refresh(TwitchAPI.Auth.t()) :: {:ok, Req.Response.t()} | {:error, term()}

Refresh an access token.

https://dev.twitch.tv/docs/authentication/refresh-tokens

If the request succeeds, the response contains the new access token, refresh token, and scopes associated with the new grant. Because refresh tokens may change, your app should safely store the new refresh token to use the next time.

{
  "access_token": "1ssjqsqfy6bads1ws7m03gras79zfr",
  "refresh_token": "eyJfMzUtNDU0OC4MWYwLTQ5MDY5ODY4NGNlMSJ9%asdfasdf=",
  "scope": [
    "channel:read:subscriptions",
    "channel:manage:polls"
  ],
  "token_type": "bearer"
}copy

The following example shows what the response looks like if the request fails.

{
  "error": "Bad Request",
  "status": 400,
  "message": "Invalid refresh token"
}copy

@spec token_refresh_step({Req.Request.t(), Req.Response.t()}) ::
  {Req.Request.t(), Req.Response.t()}

A response step (Req.Step) for refreshing tokens and re-attempting a request when authentication fails.

If the Auth struct has a client_secret and refresh_token and has not already been attempted, then we will attempt to refresh the token.

Example

Req.new(url: "https://api.twitch.com/helix/users") |> Req.Request.append_response_steps(token_refresh: &TwitchAPI.Auth.token_refresh_step/1)

@spec token_revoke(TwitchAPI.Auth.t()) :: {:ok, Req.Response.t()} | {:error, term()}

Revoke an access token.

https://dev.twitch.tv/docs/authentication/revoke-tokens

If the revocation succeeds, the request returns HTTP status code 200 OK (with no body).

If the revocation fails, the request returns one of the following HTTP status codes:

• 400 Bad Request if the client ID is valid but the access token is not.

  { "status": 400, "message": "Invalid token" }

• 404 Not Found if the client ID is not valid.

  { "status": 404, "message": "client does not exist" }

@spec token_validate(TwitchAPI.Auth.t()) :: {:ok, Req.Response.t()} | {:error, term()}

Validate an access token.

https://dev.twitch.tv/docs/authentication/validate-tokens/#how-to-validate-a-token

If the token is valid, the request returns HTTP status code 200 and the response’s body contains the following JSON object:

{
  "client_id": "wbmytr93xzw8zbg0p1izqyzzc5mbiz",
  "login": "twitchdev",
  "scopes": [
    "channel:read:subscriptions"
  ],
  "user_id": "141981764",
  "expires_in": 5520838
}copy

If the token is not valid, the request returns HTTP status code 401 and the response’s body contains the following JSON object:

{
  "status": 401,
  "message": "invalid access token"
}copy