> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paytsoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Authorization
> Authorize your app using the OAuth2 Authorization Code flow, or fall back to a static API token.
Payt uses the [OAuth2 Authorization Code](https://tools.ietf.org/html/rfc6749#section-4.1) flow for the authorization process of its public API. When unable to support OAuth2, it is also possible to use a static API token. This approach is less secure though.
In order to start the authorization process you need to have an [application](/authentication/applications). Check there how to create one if you didn't do so already.
Your users should be able to start the authorization process from within your app. A button or link should take them to the authorization form.
Here users can authorize your app to access their Payt company. They see the list of permissions your app requests and they can select which administrations they grant access to. Or they can allow your app access to all current and future administrations of their company.
If the user is already logged into their Payt user account they are immediately directed to the authorization form. Otherwise they have to go through the regular Payt login first.
When editing an application, you'll find an example authorization link that takes you to the authorization form your users will see. The url contains all parameters the server requires.
**[Request](https://tools.ietf.org/html/rfc6749#section-4.1.1) initiated by the client:**
```http theme={null}
GET https://app.paytsoftware.com/oauth/authorize?redirect_uri=https%3A%2F%2Fexample.com%2Fcallbacks%2Fpayt&response_type=code&client_id=q-QynnbDDXVFJCHUPg58EWHH2n5kCWaWYeJ5lVQNI7A&scope=debtors%3Aread%20invoices%3Aread&state=mbjk17r01c
```
| Parameter | Presence | Definition |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id` | required | The client\_id of the application. |
| `redirect_uri` | required | The URL your users are sent to after they complete the authorization process. |
| `response_type` | required | Must be: `code` |
| `state` | required | Random set of characters. This value will be returned by the Payt server and should be validated on the client side to prevent CSRF attacks. |
| `scope` | optional | When the parameter is not supplied, the scopes as defined by the application will be used. When the parameter is present, it must contain a subset of the scopes defined by the application. When multiple scopes are supplied, they must be joined into a single String separated by spaces. |
After submitting the authorization form, the server will redirect the user to the `redirect_uri` you provided.
The `state` value that was provided by the client is returned and must be checked by the client in order to prevent attackers from initiating requests.
Payt will add the `code` parameter to the redirect\_uri. The client must then complete the authorization process by sending a POST request to the token endpoint (`/oauth/token`). This request must include the `code` that was just received. The server will then generate the first [token](/authentication/tokens) and return it in the response.
The `code` expires after 10 minutes. If the client fails to fetch the first token within that window, the authorization process fails and the user has to go through it again.
**[Request](https://tools.ietf.org/html/rfc6749#section-4.1.2) initiated by the server**
```http theme={null}
GET https://example.com/callbacks/payt?code=lupjwsFG3RMGoIJAKkQBMGjs4bDuW4OP3NAqv_2XZ5o&state=mbjk17r01c
```
**Your app must make the following [request](https://tools.ietf.org/html/rfc6749#section-4.1.3)**
```http Request theme={null}
POST https://api.paytsoftware.com/oauth/token
Authorization: Basic cS1ReW5uYkREWFZGSkNIVVBnNThFV0hIMm41a0NXYVdZZUo1bFZRTkk3QTpNcTRFMlZGTnNzcjVpQTdaN0xBZFM4MnZtNTl3Qm9nNVE1SGw2Si1Pc0w0
{
"code": "lupjwsFG3RMGoIJAKkQBMGjs4bDuW4OP3NAqv_2XZ5o",
"grant_type": "authorization_code",
"redirect_uri": "https://example.com/callbacks/payt"
}
```
```bash cURL theme={null}
curl --header 'Authorization: Basic cS1ReW5uYkREWFZGSkNIVVBnNThFV0hIMm41a0NXYVdZZUo1bFZRTkk3QTpNcTRFMlZGTnNzcjVpQTdaN0xBZFM4MnZtNTl3Qm9nNVE1SGw2Si1Pc0w0' \
--form code=lupjwsFG3RMGoIJAKkQBMGjs4bDuW4OP3NAqv_2XZ5o \
--form grant_type=authorization_code \
--form redirect_uri=https://example.com/callbacks/payt \
--request POST https://api.paytsoftware.com/oauth/token
```
| Header | Presence | Definition |
| --------------- | -------- | -------------------------------------------- |
| `Authorization` | required | [Basic](/authentication/basic-authorization) |
| Parameter | Presence | Definition |
| -------------- | -------- | ----------------------------------------------------------------------------- |
| `code` | required | Must be the code that was included in the url. |
| `grant_type` | required | Must be: `authorization_code` |
| `redirect_uri` | required | The URL your users are sent to after they complete the authorization process. |
**[Response](https://tools.ietf.org/html/rfc6749#section-4.1.4) from the server**
```json theme={null}
{
"access_token": "IBzLDErQvt9gOmSLarUtDy06emduHZmKEG2OSPdHpJ8",
"created_at": 1585820684,
"expires_in": 7200,
"refresh_token": "2_L56FQ1Sl6db15XJuO14KysWEwGhwaMsVeUegGBxfI",
"scope": "invoices:read debtors:read",
"token_type": "Bearer"
}
```
| Key | Value |
| --------------- | -------------------------------------------------------------- |
| `access_token` | The token that can be used to authenticate API requests. |
| `created_at` | The unix time at which the token was created. |
| `expires_in` | The number of seconds the access token is valid. |
| `refresh_token` | The new refresh\_token, must be used to create the next token. |
| `scope` | List of granted permissions. |
| `token_type` | Will always be `Bearer`. |
At the very minimum your app must store the access token and refresh token. The access token is required to use the API, the refresh\_token to create a new token. It is recommended to also store the expiration time of the access token. It allows you to request a new token just before the current token expires, minimizing the number of requests needed.
More information on how to use tokens can be found [here](/authentication/tokens).
## Re-authorization
After the authorization process has been completed, it can always be started again. When completed, all tokens from the previous authorization are immediately removed. Also the previously granted scopes and administrations are removed and replaced by what is authorized during this last process. Under normal conditions it should not be required for a user to go through this process more than once. It can however be initiated by the client when the refresh\_token is lost or when it expired.