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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.optty.com/partner-onboarding-docs/api-scopes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.