# API Scopes

When interacting with Optty's APIs, the API scope you use is crucial, as it determines the level of access and the entity you are acting on behalf of.

There is a key distinction between the scopes used for payment processing and those used for configuration.

* The `api-user` scope is specifically used on the APIs that handle taking payments.
* The `merchant` scope, on the other hand, is used to act on behalf of a merchant when configuring their setup. This is part of the Partner APIs.

When generating a token for the Partner APIs, the scope will be one of the following:

* `merchant`
* `parent`
* `grandparent`

The credentials used to generate this token will specify which merchant, parent, or grandparent you are performing actions for, ensuring all actions are correctly attributed within the hierarchy.

## Generating Token

<mark style="color:green;">`POST`</mark> `/token`

#### Headers

| Name                                           | Type | Description                       |
| ---------------------------------------------- | ---- | --------------------------------- |
| content-type<mark style="color:red;">\*</mark> |      | application/x-www-form-urlencoded |

#### Request Body

| Name                                             | Type   | Description                                                                                                                                                                                                                     |
| ------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| client\_id<mark style="color:red;">\*</mark>     | string | The Client ID credential provided by Optty for the specific merchant, parent, or grandparent you are generating a token for.                                                                                                    |
| client\_secret<mark style="color:red;">\*</mark> | string | The Client Secret credential provided by Optty, which corresponds to the `client_id` you are using.                                                                                                                             |
| grant\_type<mark style="color:red;">\*</mark>    | string | Always “client\_credentials”                                                                                                                                                                                                    |
| scope<mark style="color:red;">\*</mark>          | string | <p>The hierarchical level that defines the permissions for the generated token. The scope must be one of the following:</p><ul><li><code>merchant</code></li><li><code>parent</code></li><li><code>grandparent</code></li></ul> |