GitHub REST API Client v0.3.3

View Source GitHub.Auth protocol (GitHub REST API Client v0.3.3)

Protocol for extracting API authentication tokens from application structs

Credentials can be passed to operations using the auth option as strings (for tokens) or 2-tuples (for client ID / secret or username / password). Sometimes, it's more convenient to pass a struct — like as a user struct — and extract the auth token from that.

By implementing this protocol, the client can extract an auth token from the given struct without additional work by the caller.

example

 Example 

defimpl GitHub.Auth, for: MyApp.User do
  def to_auth(%MyApp.User{github_token: token}), do: token
end

provided-implementations

 Provided Implementations

This library provides several implementations for the protocol based on library structs.

github-app

 GitHub.App

For app structs with id and pem fields containing the GitHub App ID and private key (respectively), the default implementation will generate a JWT compatible with certain API endpoints. Generally, the PEM field can only be filled in manually. To assist with this, the helper function GitHub.app/1 will construct a valid app struct using configured values.

Creating a JWT requires the optional dependency JOSE.

JWTs are made to last for several minutes, so it is prudent to cache values between requests. See GitHub.Auth.Cache for a built-in caching mechanism.

Link to this section Summary

Types

auth()

Auth token accepted by the client

t()

Functions

to_auth(value)

Extract an auth token from the given struct

Link to this section Types

Link to this type

auth()

View Source 
@type auth() ::
  nil
  | (token :: String.t())
  | {username_or_client_id :: String.t(),
     password_or_client_secret :: String.t()}

Auth token accepted by the client

Link to this type

t()

View Source 
@type t() :: term()

Link to this section Functions

Link to this function

to_auth(value)

View Source 
@spec to_auth(t()) :: auth()

Extract an auth token from the given struct

The returned data should be in the form of a string (for a Bearer token) or a 2-tuple (for a Basic Auth user/password pair).