Authentication

API client

When you start building an integration with the Agrello platform your application is referred to as API client.

To use Agrello API you need an API-key for your API-client.

Please send a request to [e-mail] 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

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. ‍ https://service.agrello.org/identity/auth/oauth/authorize?response_type=code&client_id=MYAPP_CLIENT_ID&redirect_uri=http://myapp.io/auth/agrello

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.