* rename AccessTokens

* add doc

github4s/src/main/scala/github4s/Github.scala

@@ -18,13 +18,13 @@ package github4s
 
 import cats.effect.Sync
 import github4s.algebras._
-import github4s.interpreters.StaticAccessTokens
+import github4s.interpreters.StaticAccessToken
 import github4s.modules._
 import org.http4s.client.Client
 
 class Github[F[_]: Sync](
     client: Client[F],
-    accessToken: AccessTokens[F]
+    accessToken: AccessToken[F]
 )(implicit config: GithubConfig)
     extends GithubAPIs[F] {
 
@@ -49,5 +49,5 @@ object Github {
       client: Client[F],
       accessToken: Option[String] = None
   )(implicit config: GithubConfig): Github[F] =
-    new Github[F](client, new StaticAccessTokens(accessToken))
+    new Github[F](client, new StaticAccessToken(accessToken))
 }

github4s/src/main/scala/github4s/algebras/AccessToken.scala

@@ -0,0 +1,17 @@
+package github4s.algebras
+
+import github4s.GHResponse
+
+/**
+ * Source of static or expiring github tokens
+ *
+ * For github app authentication you'd want to create a token source
+ * which calls github's installation authentication api with a jwt token, generated from a private key
+ * These tokens have a 1h lifetime, so it's a good idea to handle expired tokens here as well
+ *
+ * @see https://docs.github.com/en/free-pro-team@latest/developers/apps/authenticating-with-github-apps
+ */
+trait AccessToken[F[_]] {
+
+  def withAccessToken[T](f: Option[String] => F[GHResponse[T]]): F[GHResponse[T]]
+}

github4s/src/main/scala/github4s/http/HttpClient.scala

@@ -23,7 +23,7 @@ import cats.syntax.either._
 import cats.syntax.functor._
 import github4s.GHError._
 import github4s._
-import github4s.algebras.AccessTokens
+import github4s.algebras.AccessToken
 import github4s.domain.Pagination
 import github4s.http.Http4sSyntax._
 import io.circe.{Decoder, Encoder}
@@ -35,7 +35,7 @@ import org.http4s.{EntityDecoder, Request, Response, Status}
 class HttpClient[F[_]: Sync](
     client: Client[F],
     val config: GithubConfig,
-    accessTokens: AccessTokens[F]
+    accessTokens: AccessToken[F]
 ) {
   import HttpClient._
   import accessTokens._

github4s/src/main/scala/github4s/interpreters/StaticAccessTokens.scala → github4s/src/main/scala/github4s/interpreters/StaticAccessToken.scala

@@ -1,17 +1,17 @@
 package github4s.interpreters
 
 import github4s.GHResponse
-import github4s.algebras.AccessTokens
+import github4s.algebras.AccessToken
 
 /**
  * A simple static version
  */
-class StaticAccessTokens[F[_]](accessToken: Option[String]) extends AccessTokens[F] {
+class StaticAccessToken[F[_]](accessToken: Option[String]) extends AccessToken[F] {
 
   override def withAccessToken[T](f: Option[String] => F[GHResponse[T]]): F[GHResponse[T]] =
     f(accessToken)
 }
 
-object StaticAccessTokens {
-  def noToken[F[_]] = new StaticAccessTokens[F](None)
+object StaticAccessToken {
+  def noToken[F[_]] = new StaticAccessToken[F](None)
 }

github4s/src/main/scala/github4s/modules/GithubAPIs.scala

@@ -26,7 +26,7 @@ import org.http4s.client.Client
 class GithubAPIv3[F[_]: Sync](
     client: Client[F],
     config: GithubConfig,
-    accessToken: AccessTokens[F]
+    accessToken: AccessToken[F]
 ) extends GithubAPIs[F] {
 
   implicit val httpClient = new HttpClient[F](client, config, accessToken)
@@ -48,5 +48,5 @@ class GithubAPIv3[F[_]: Sync](
 object GithubAPIv3 {
 
   def noAuth[F[_]: Sync](client: Client[F], config: GithubConfig) =
-    new GithubAPIv3[F](client, config, StaticAccessTokens.noToken)
+    new GithubAPIv3[F](client, config, StaticAccessToken.noToken)
 }

github4s/src/test/scala/github4s/utils/BaseSpec.scala

@@ -19,7 +19,7 @@ package github4s.utils
 import cats.effect.IO
 import github4s.domain.Pagination
 import github4s.http.HttpClient
-import github4s.interpreters.StaticAccessTokens
+import github4s.interpreters.StaticAccessToken
 import github4s.{GHResponse, GithubConfig}
 import io.circe.{Decoder, Encoder}
 import org.http4s.client.Client
@@ -40,7 +40,7 @@ trait BaseSpec extends AnyFlatSpec with Matchers with TestData with MockFactory
 
   @com.github.ghik.silencer.silent("deprecated")
   class HttpClientTest
-      extends HttpClient[IO](mock[Client[IO]], implicitly, new StaticAccessTokens(sampleToken))
+      extends HttpClient[IO](mock[Client[IO]], implicitly, new StaticAccessToken(sampleToken))
 
   def httpClientMockGet[Out](
       url: String,

microsite/docs/docs.md

@@ -10,6 +10,8 @@ permalink: docs
 
 In order to access the Github API, you will need to have [an access token][access-token] with the
 appropriate scopes (i.e. if you want to create gists, your token will need to have the gist scope).
+A personal token lives forever, github app's one has to be re-issued every hour. 
+Implementation of [github app][github_app] authentication involves 3rd party libraries like jwt and is left for the user. 
 
 ## Github4s
 
@@ -240,6 +242,7 @@ headers which will be added to every request sent to the GitHub API. The user ag
 added by default.
 
 [access-token]: https://github.com/settings/tokens
+[github_app]: https://github.com/settings/apps
 [cats-sync]: https://typelevel.org/cats-effect/typeclasses/sync.html
 [monix-task]: https://monix.io/docs/3x/eval/task.html
 [http4s-client]: https://http4s.org/v0.21/client/