# Complete the WebPros authentication flow

This function completes the WebPros single sign-on flow for
360 Monitoring.

Call this function after the WebPros authorization server redirects the
user back to the server. The function exchanges the authorization code
for a token bundle and stores that bundle on the server. It does not
return the access token or the refresh token. Use the
360Monitoring/webpros_auth_token function to retrieve the access
token.

This function accepts its arguments as a single JSON-encoded json
parameter, and it requires that parameter in the request body. The
authorization code is a secret, and the server records the URL query
string in its access log. The function therefore rejects a request that
is not an HTTP POST, and also rejects a json parameter that appears
in the query string of a POST.

The function returns data.success with a value of 1 when it stores
a token. If the function fails, it returns data.success with a value
of 0, a human-readable data.error message, and, for the failures
that it detects before it contacts the authorization server, a
machine-readable data.reason value.

Endpoint: POST /360Monitoring/webpros_auth_callback
Version: 11.138.0.10
Security: BasicAuth

## Request fields (application/x-www-form-urlencoded):

  - `json` (string, required)
    A JSON-encoded object that contains the callback arguments.

The object accepts the following keys:
* code - Required. The authorization code that the WebPros authorization server returned.
* state - Required. The state value that the WebPros authorization server returned. It must carry the state token that the 360Monitoring/webpros_auth_start function issued for this flow. The system uses this value to confirm that the callback belongs to the flow that this server started.
* session_id - Optional. The WHM session that this sign-in belongs to, as digits. The system uses this key only when the request itself carries no session, which is the case for callers that authenticate with an API token or with HTTP Basic authentication. A session taken from the request always takes precedence, so a caller inside a session cannot claim a different one.
* verifier - Ignored. The system keeps the Proof Key for Code Exchange (PKCE) verifier on the server, so 360Monitoring/webpros_auth_start does not return one and this function does not read one. The function accepts this key without error so that existing callers keep working, and a later release will remove it.

The function returns a data.reason value of
invalid_json when it cannot decode this parameter or when
the parameter does not hold a JSON object, and a
data.reason value of missing_parameter when the
parameter is absent, when the object does not contain the
code key, or when the system cannot determine which WHM
session the callback belongs to.

The system verifies the state value before it contacts
the authorization server, so it never exchanges the
authorization code when the state is absent, does not
match, was issued to a different WHM session, or has
expired. The stored state is single-use: the system
consumes the matching state whether the sign-in then
succeeds or fails, which means a callback cannot be
replayed and a retry requires a new call to
360Monitoring/webpros_auth_start. A callback whose state
matches no sign-in in progress consumes nothing, and
neither does one whose state was issued to another
administrator's session, so a callback cannot cancel a
sign-in that someone else started.
    Example: "{\"code\":\"SplxlOBeZQQYbYS6WxSbIA\",\"state\":\"Xk7fQ2mR9vLpN4wCbT8yHzA1sD6gJ3eU0iO5nY7kV2q\"}"

## Response 200 fields (application/json):

  - `data` (object)

  - `data.error` (string)
    The error message. The function only returns this
field if the authentication fails.
    Example: "The “code” parameter is required."

  - `data.reason` (string)
    The machine-readable reason that the authentication
failed. The function returns this field for the
failures that it detects before it contacts the
WebPros authorization server, and for a stored token
that the system cannot use. It omits the field when
the exchange with the authorization server itself
failed.

It is one of the following values:
* invalid_transport - The request was not an HTTP POST, or it carried the json parameter in the URL query string. Send the parameter in the request body.
* invalid_json - The system could not decode the json parameter, or the parameter does not hold a JSON object.
* missing_parameter - The json parameter is absent, the object does not contain the code key, or the system could not determine which WHM session the callback belongs to.
* invalid_parameter - The session_id key is not a number.
* invalid_state - The state value does not match a flow that this server started for this WHM session.
* expired_state - The state value belongs to a flow that is no longer current.
* token_unusable - The system stored the token but cannot use it, for example, if the identity token had already expired. Start a new sign-in.
    Example: "missing_parameter"

  - `data.success` (integer)
    * 1 - The system stored a WebPros authentication token.
* 0 - The authentication failed. Check the data.reason and data.error fields for more details.
    Enum: 0, 1

  - `data.token_data` (object)
    A summary of the stored token. The function only
returns this field when the authentication succeeds.
It never contains the access token or the refresh
token.

  - `data.token_data.email` (string)
    The email address from the email claim of the
identity token. The system omits this field when
the identity token does not contain an email
claim.
    Example: "user@example.com"

  - `data.token_data.expires_in` (integer)
    The number of seconds until the stored token expires.
    Example: 900

  - `metadata` (object)

  - `metadata.command` (string)
    The method name called.
    Example: "webpros_auth_callback"

  - `metadata.namespace` (string)
    The namespace used in the API call.
    Example: "360Monitoring"

  - `metadata.reason` (string)
    The reason the API function failed when the metadata.result
field is 0. This field may display a success message when
a function succeeds.
    Example: "OK"

  - `metadata.result` (integer)
    * 1 - Success.
* 0 - Failed. Check the reason field for more details.
    Enum: 0, 1

  - `metadata.version` (integer)
    The version of the API function.
    Example: 1