-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_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 (e.g., hostname of the device)

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}}