> For the complete documentation index, see [llms.txt](https://agrello.gitbook.io/agrello-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://agrello.gitbook.io/agrello-api/authentication.md).
# Authentication
### API client
When you start building an integration with the Agrello platform your application is referred to as **API client**.
{% hint style="info" %}
**To use Agrello API you need an API-key for your API-client.**
\
Please send a request to to get your API key (client\_secret).
Please note, that the client\_secret should be kept in secret and only used in backend-to-backend communication.
Never use client\_secret in frontend-to-backend communication
{% endhint %}
### API-user
The identity that creates documents, sends signature requests etc over API is called **API-user** (or simply user in this documentation).
Before your application can access private data using Agrello platform API, it must obtain an access token for an API-user that grants access to that API.
A single access token can grant varying degrees of access to multiple APIs. A variable parameter called scope controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter.
There are several ways to make this request, and they vary based on the type of application you are building. For example, a JavaScript application might request an access token using a browser redirect to Agrello platform.
Some requests require an authentication step where the user logs in with their Agrello account. After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent.
If the user grants permission, the Agrello platform sends your application an authorization code that your application can use to obtain an access token. If the user does not grant permission, the server returns an error.
### Authentication flow
* Your application opens a browser to send the user to Agrello platform OAuth server
* The user sees the authorization prompt and approves the app’s request
* The user enters his login username and confirms authentication using Agrello application
* The user is redirected back to the application with an authorization code in the query string
* The application exchanges the authorization code for an access token
#### 1. Start authorization
Build authorization URL with your configuration parameters. Open this URL in a browser.
As a result authorization server will redirect you to the sign-in page
#### 2. User login
The user enters his username and confirms signing in using either the mobile application or OTP sent to email.
As a result, user will be redirected to your redirect\_uri with the issued authorization code.
This code should be used to retrieve the access token.
#### 3. Retrieve user access token
Your backend should use an authorization code from a callback and client credentials to retrieve an access token.
This call requires a basic authorization header using your client\_id as a username and client\_secret as a password.
After an application obtains an access token, it sends the token to Agrello API in an HTTP authorization header. Access tokens are valid only for the set of operations and resources described in the scope of the token request.
#### 4. Refresh the access token, if necessary.
Access tokens have limited lifetimes. If your application needs access to Agrello API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens.