Documentation

This method is called on a valid authorization token request. The $data array is guaranteed to have the following keys:

• client_id: the validated client_id request parameter
• redirect_uri: the validated redirect_uri request parameter
• state: the state request parameter
• code_challenge: the code_challenge request parameter
• code_challenge_method: the code_challenge_method request parameter
• requested_scope: the value of the scope request parameter
• me: the value of the me key from the authentication result returned from the authentication request handler callback

It may also have additional keys, which can come from the following locations:

• All keys from the the authentication request handler callback result which do not clash with the keys listed above (with the exception of me, which is always present). Usually this is a profile key, but you may choose to return additional data from the authentication callback, which will be present in $data.
• Any keys added by the transformAuthorizationCode method on the currently active instance of Taproot\IndieAuth\Callback\AuthorizationFormInterface. Typically this is the scope key, which is a valid space-separated scope string listing the scopes granted by the user on the consent screen. Other implementations of AuthorizationFormInterface may add additional data, such as custom token-specific settings, or a custom token lifetime.

This method should store the data passed to it, generate a corresponding authorization code string, and return it.

The method call and data is structured such that implementations have a lot of flexibility about how to store authorization code data. It could be a record in an auth code database table, a record in a table which is used for both auth codes and access tokens, or even a stateless self-encrypted token — note that in the latter case, you must persist a copy of the auth code with its exchanged access token to check against, in order to prevent it being exchanged more than once.

On an error, return null. The reason for the error is irrelevant for calling code, but it’s recommended to log it internally for reference. For the same reason, this method should not throw exceptions.

Attempt to exchange an authorization code identified by $code for an access token. Return an array of access token data to be passed onto the client app on success, and null on error.

This method is called at the beginning of a code exchange request, before further error checking or validation is applied. It should proceed as follows.

• Attempt to fetch the authorization code data identified by $code. If it does not exist or has expired, return null;
• Pass the authorization code data array to $validateAuthCode for validation. If there is a problem with the code, a Taproot\IndieAuth\IndieAuthException will be thrown. This method should catch it, invalidate the authorization code data, then re-throw the exception for handling by Server.
• If the authorization code data passed all checks, convert it into an access token, invalidate the auth code to prevent re-use, and store the access token data internally.
• Return an array of access token data to be passed onto the client app. It MUST contain the following keys:
  • me
  • access_token Additonally, it SHOULD contain the following keys:
  • scope, if the token grants any scope And MAY contain additional keys, such as:
  • profile
  • expires_at

If the authorization code was redeemed at the authorization endpoint, Server will only pass the me and profile keys onto the client. In both cases, it will filter out code_challenge keys to prevent that data from accidentally being leaked to clients. If an access token is present, the server will add token_type: Bearer automatically.

A typical implementation might look like this:

function exchangeAuthCodeForAccessToken(string $code, callable $validateAuthCode): ?array {
  if (is_null($authCodeData = $this->fetchAuthCode($code))) {
    return null;
  }

  if (isExpired($authCodeData)) {
    return null;
  }

  try {
    $validateAuthCode($authCodeData);
  } catch (IndieAuthException $e) {
    $this->deleteAuthCode($code);
    throw $e;
  }

  return $this->newTokenFromAuthCodeData($authCodeData);
}

Refer to reference implementations in the Taproot\IndieAuth\Storage namespace for reference.

An array of access token data to return to the client on success, null on any error.

Fetch access token data identified by the token $token, returning null if it is expired or invalid.

Revoke the access token identified by $token. Return true on success, or false on error, including if the token did not exist.