-spec client_credentials_token(hex_core:config(), binary(), binary(), binary()) -> hex_api:response().

Exchanges an API key for an OAuth access token using the client credentials grant.

See also: client_credentials_token/5.

-spec client_credentials_token(hex_core:config(), binary(), binary(), binary(), proplists:proplist()) ->
                                  hex_api:response().

Exchanges an API key for an OAuth access token using the client credentials grant with optional parameters.

This grant type allows exchanging a long-lived API key for a short-lived OAuth access token. The API key is sent as the client_secret parameter.

Options: * name - A name to identify the token (e.g., hostname of the client)

Returns: - {ok, {200, _, Token}}` - Token exchange successful - `{ok, {400, _, #{<<"error">> => ...}}}` - Invalid request or scope - `{ok, {401, _, #{<<"error">> => ...}}}` - Invalid API key Examples: ``` 1> Config = hex_core:default_config(). 2> hex_api_oauth:client_credentials_token(Config, <<"cli">>, ApiKey, <<"api">>). {ok, {200, _, #{ <<"access_token">> => <<"...">>, <<"token_type">> => <<"bearer">>, <<"expires_in">> => 1800, <<"scope">> => <<"api">> }}} 3> hex_api_oauth:client_credentials_token(Config, <<"cli">>, ApiKey, <<"api">>, [{name, <<"MyMachine">>}]).''

-spec device_auth_flow(hex_core:config(),
                       ClientId :: binary(),
                       Scope :: binary(),
                       PromptUser :: fun((VerificationUri :: binary(), UserCode :: binary()) -> ok)) ->
                          {ok, oauth_tokens()} | {error, device_auth_error()}.

Runs the complete OAuth device authorization flow.

See also: device_auth_flow/5.

-spec device_auth_flow(hex_core:config(),
                       ClientId :: binary(),
                       Scope :: binary(),
                       PromptUser :: fun((VerificationUri :: binary(), UserCode :: binary()) -> ok),
                       proplists:proplist()) ->
                          {ok, oauth_tokens()} | {error, device_auth_error()}.

Runs the complete OAuth device authorization flow with options.

This function handles the entire device authorization flow: 1. Requests a device code from the server 2. Calls PromptUser callback with the verification URI and user code 3. Optionally opens the browser for the user (when open_browser is true) 4. Polls the token endpoint until authorization completes or times out

The PromptUser callback is responsible for displaying the verification URI and user code to the user (e.g., printing to console).

Options: * name - A name to identify the token (defaults to the machine's hostname) * open_browser - When true, automatically opens the browser to the verification URI. When false (default), only the callback is invoked.

Returns: - {ok, Tokens} - Authorization successful, returns access token and optional refresh token - {error, timeout} - Device code expired before user completed authorization - {error, {access_denied, Status, Body}} - User denied the authorization request - {error, {device_auth_failed, Status, Body}} - Initial device authorization request failed - {error, {poll_failed, Status, Body}} - Unexpected error during polling

Examples:

  1> Config = hex_core:default_config().
  2> PromptUser = fun(Uri, Code) ->
         io:format("Visit ~s and enter code: ~s~n", [Uri, Code])
     end.
  3> hex_api_oauth:device_auth_flow(Config, <<"cli">>, <<"api:write">>, PromptUser).
  {ok, #{
      access_token => <<"...">>,
      refresh_token => <<"...">>,
      expires_at => 1234567890
  }}

-spec device_authorization(hex_core:config(), binary(), binary()) -> hex_api:response().

Initiates the OAuth device authorization flow.

See also: device_authorization/4.

-spec device_authorization(hex_core:config(), binary(), binary(), proplists:proplist()) ->
                              hex_api:response().

Initiates the OAuth device authorization flow with optional parameters.

Returns device code, user code, and verification URIs for user authentication.

Options: * name - A name to identify the token (defaults to the machine's hostname)

Examples:

  1> Config = hex_core:default_config().
  2> hex_api_oauth:device_authorization(Config, <<"cli">>, <<"api:write">>).
  {ok,{200, ..., #{
      <<"device_code">> => <<"...">>,
      <<"user_code">> => <<"ABCD-1234">>,
      <<"verification_uri">> => <<"https://hex.pm/oauth/device">>,
      <<"verification_uri_complete">> => <<"https://hex.pm/oauth/device?user_code=ABCD-1234">>,
      <<"expires_in">> => 600,
      <<"interval">> => 5
  }}}
 
  3> hex_api_oauth:device_authorization(Config, <<"cli">>, <<"api:write">>, [{name, <<"MyMachine">>}]).

-spec poll_device_token(hex_core:config(), binary(), binary()) -> hex_api:response().

Polls the OAuth token endpoint for device authorization completion.

Returns: - {ok, {200, _, Token}}` - Authorization complete - `{ok, {400, _, #{<<"error">> => <<"authorization_pending">>}}}` - Still waiting - `{ok, {400, _, #{<<"error">> => <<"slow_down">>}}}` - Polling too fast - `{ok, {400, _, #{<<"error">> => <<"expired_token">>}}}` - Code expired - `{ok, {403, _, #{<<"error">> => <<"access_denied">>}}}` - User denied Examples: ``` 1> Config = hex_core:default_config(). 2> hex_api_oauth:poll_device_token(Config, <<"cli">>, DeviceCode). {ok, {200, _, #{ <<"access_token">> => <<"...">>, <<"refresh_token">> => <<"...">>, <<"token_type">> => <<"Bearer">>, <<"expires_in">> => 3600 }}}''

-spec refresh_token(hex_core:config(), binary(), binary()) -> hex_api:response().

Refreshes an access token using a refresh token.

Examples:

  1> Config = hex_core:default_config().
  2> hex_api_oauth:refresh_token(Config, <<"cli">>, RefreshToken).
  {ok, {200, _, #{
      <<"access_token">> => <<"...">>,
      <<"refresh_token">> => <<"...">>,
      <<"token_type">> => <<"Bearer">>,
      <<"expires_in">> => 3600
  }}}

-spec revoke_token(hex_core:config(), binary(), binary()) -> hex_api:response().

Revokes an OAuth token (RFC 7009).

Can revoke either access tokens or refresh tokens. Returns 200 OK regardless of whether the token was found, following RFC 7009 security recommendations.

Examples:

  1> Config = hex_core:default_config().
  2> hex_api_oauth:revoke_token(Config, <<"cli">>, Token).
  {ok, {200, ..., nil}}