# revoke

> Use this API to cancel a user's authorization to a merchant. The access token becomes invalid after Antom receives the revoke request, and the merchant can no longer access the user resource scope with the access token. In addition, the merchant cannot use the related refresh token to obtain a new access token.

`POST /v1/authorizations/revoke`

Use this API to cancel a user's authorization to a merchant. The access token becomes invalid after Antom receives the revoke request, and the merchant can no longer access the user resource scope with the access token. In addition, the merchant cannot use the related refresh token to obtain a new access token. 

# Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see： 

-   [Request header](https://docs.antom.com/ac/ams/api_fund.md#ML5ur)
-   [Response header](https://docs.antom.com/ac/ams/api_fund.md#WWH90)

> **Note**: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:
>
> -   If the data type of a field is Integer and its value is `20`, set it as "`20`". 
> -   If the data type of a field is Boolean and its value is `true`, set it as "`true`".

## Request parameters

#### accessToken (String, REQUIRED)

The access token that is used to access the corresponding scope of the user resource.

More information:

- Maximum length: 128 characters

#### merchantAccountId (String)

A unique ID to identify a specific merchant account.

> **Note**: Specify this parameter when you use one client ID across multiple locations.

More information:

- Maximum length: 64 characters

## Response parameters

#### result (Result, REQUIRED)

Indicates whether this API is called successfully. If this API is successfully called, the authorization is canceled successfully.

##### resultCode (String, REQUIRED)

Result code. Possible values are listed in the Result/Error codes table on this page.

More information:

- Maximum length: 64 characters

##### resultStatus (String, REQUIRED)

Result status. Valid values are:

-   `S`: Indicates that this API is called successfully and the authorization is canceled successfully.
-   `F`: Indicates that this API call failed. The authorization cancelation failed.
-   `U`: Indicates that the call status of this API is unknown. Retry the call process.

##### resultMessage (String, REQUIRED)

Result message that explains the result code.

More information:

- Maximum length: 256 characters

## Result process logic

For different request results, different actions are to be performed. See the following list for details:

-   If the value of _result.resultStatus_ is `S`, the authorization is successfully canceled. The access token cannot be used to access the user's resources anymore. In addition, the relative _refreshToken_ cannot be used to update _accessToken_ anymore_._
-   If the value of _result.resultStatus_ is `F`, system defects or system failure occurred. It is suggested to check the system manually and take actions according to the result code.
-   If the value of _result.resultStatus_ is `U`, the call status of this API is unknown. Retry the process by calling this API again.

## Result/Error codes

| Code | Value | Message | Further action |
| --- | --- | --- | --- |
| SUCCESS | S | Success | Revoke successful. The access token is invalid. |
| ACCESS_DENIED | F | Access is denied. | Contact Antom Technical Support for detailed reasons. |
| CLIENT_FORBIDDEN_ACCESS_API | F | The client is not authorized to use this API. | Contact Antom Technical Support for detailed reasons. |
| INVALID_ACCESS_TOKEN | F | The access token is expired, revoked, or does not exist. | Check whether accessToken is correct. If not correct, pass in the correct value. If correct, contact Antom Technical Support for detailed reasons. |
| INVALID_API | F | The called API is invalid or not active. | Contact Antom Technical Support to resolve the issue. |
| INVALID_CLIENT_STATUS | F | The client status is invalid. | Contact Antom Technical Support for detailed reasons. |
| INVALID_SIGNATURE | F | The signature is not validated. The private key used to sign a request does not match the public key of Antom Dashboard. | Check whether the private key used to sign a request matches the public key of Antom Dashboard. The following signature references are useful:The signature field in a request header How to calculate a signature |
| KEY_NOT_FOUND | F | The private key or public key of Antom or the merchant is not found. | Check whether the private key or public key exists. If not, upload the private key in Antom Dashboard. |
| NO_INTERFACE_DEF | F | API is not defined. | Check whether the URL is correct. Please refer to the endpoint in the API documentation. |
| OAUTH_FAILED | F | OAuth process failed. | Contact Antom Technical Support for detailed reasons. |
| PARAM_ILLEGAL | F | The required parameters are not passed, or illegal parameters exist. For example, a non-numeric input, an invalid date, or the length and type of the parameter are wrong. | Check and verify whether the required request fields (including the header fields and body fields) of the current API are correctly passed and valid. |
| PROCESS_FAIL | F | A general business failure occurred. | Do not retry. Human intervention is usually needed. It is recommended that you contact Antom Technical Support to troubleshoot the issue. |
| SYSTEM_ERROR | F | A system error occurred. | Do not retry, and contact Antom Technical Support for more details. |
| UNKNOWN_CLIENT | F | The client is unknown. | Contact Antom Technical Support for detailed reasons. |
| REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. | Call the interface again to resolve the issue. If not resolved, contact Antom Technical Support. |
| UNKNOWN_EXCEPTION | U | An API call has failed, which is caused by unknown reasons. | Call the interface again to resolve the issue. If not resolved, contact Antom Technical Support. |

## Request

```json
{
  "merchantAccountId": "2188234232",
  "accessToken": "281010033AB2F588D14B43238637264FCA5Axxxx"
}
```

## Response

### SUCCESS

```json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  }
}
```

### INVALID_ACCESS_TOKEN

```json
{
  "result": {
    "resultCode": "INVALID_ACCESS_TOKEN",
    "resultMessage": "The access token is expired, revoked, or does not exist.",
    "resultStatus": "F"
  }
}
```