# Authentication

## Requirements

EverReal APIs supports jwt tokens using [Bearer token](https://jwt.io/introduction) according to [RFC-7519](https://datatracker.ietf.org/doc/html/rfc7519). This allows us to protect our information and make sure, who is requesting has correct authorization to execute the operation.

#### OAuth 2.0 Password Grant

**Important!** You should use the password grant only in server-to-server communication, where you completely trust the client. 

This allows you to use the username and password to get the `refresh_token`. After `refresh_token` is obtain, username and password is not needed.

## Authentication

<mark style="color:green;">`POST`</mark> `https://{custom_subdomain}.everreal.co/accounts/oauth/token`

#### Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | string | `application/json` |

#### Request Body

| Name         | Type   | Description                                                                                                                                                                                                                                                                                                                                |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Payload body | object | <p><code>{</code> <br><code>"username": "<john.doe@everreal.co>",</code> <br><code>"password": "Password",</code> <br><code>"client\_id": "\<Client\_iD>",</code> <br><code>"client\_secret": "\<Client Secret>",</code> <br><code>"scope": "offline\_access \*",</code> <br><code>"grant\_type": "password"</code> <br><code>}</code></p> |

{% tabs %}
{% tab title="200 " %}

```
{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJjYTdhZDI2MC1mNmE3LTQ1OWEtOWNjYy1kNTMzMzNjY2M1Y2EiLCJzdWIiOiI3NmFmY2FiMC02NTJiLTQ1NDctODAxYi03YzcwMWMwOTdiODEiLCJleHAiOjE2Mjg1OTYyNTYsImlhdCI6MTYyODU5MjY1Nn0.nnBmf0r7oTsqDYxwkA9seO-aZGhLY3z-ZodFn2NSa9gPOxCCtXvACj7UNIifd03KbqLDiJcpqj5anUzyKpXY0taXRCPMVHB78iVYDyKR8rZqNZ7PP8XSXvxxLaZPfTiqYG01pzCgaDWHwgpUsBoFRJDr2rPt1ShD6Pe-efcZIQfS81jGUAw4dYAwnot6zNC6uNY8OkihEUEwnsVI1mCfjvmrWL6cHmL-YSko-gPUGAjF1ulSJZ68CcMTrsC2tXnWLAMyiJMu9_VWoLXUgQJH2FzISeJkyPCJbnzDlMmAYfe8Kq0z8QL_l2q_cs2aOAvre-jJpyri-dsP-6hR2ODL4g",
    "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI2ZWU5YzFhNi1hMWM5LTQwOWQtYjJjOS03NjdlZGRlMzAwNDQiLCJzdWIiOiI3NmFmY2FiMC02NTJiLTQ1NDctODAxYi03YzcwMWMwOTdiODEiLCJleHAiOjE2MzExODQ2NTYsImlhdCI6MTYyODU5MjY1Nn0.IcdmncHIE3PTxix5QS5bZAm3JsPDprRqyEU6pEk09mViV-V9F8EWlYofDuQglfB5vNe_oBzZWmu3wdxGm7hO-9Z_sveI6OEBy-mv_-bHarIRytToH7zjSkl4BO_l-s48hwxGVYyQLtFX1G9vU-ykJ4Bwd4M6V1Z-0gwW65MCFn6CXgAz8lXgDLoLorwoxGjZVMKFmjNQcNLLdcLXDNXXYdU6d2bjJQLz6hzixbqhUFYbR6hZUbEJ6cBZsKWZjsvDydtJ9froWR3d4C4tbYkirmSGvZHjvtwVrjKnoHtAd0MQ8UVTKxrH7jTcATrCmWDaxyW2XFcd7HtuI3_TdQH8aw",
    "expires_in": 3600,
    "token_type": "Bearer"
}
```

{% endtab %}

{% tab title="403 " %}

```
{
    "error": "invalid_grant",
    "error_description": "heimdall.validation.user.does.not.exist"
}
```

{% endtab %}
{% endtabs %}

* Make sure to store the `refresh_token` securely.
* Currently the `refresh_token` has an expiration between 4 weeks and 2 years, it is configurable

  by EverReal for each customer. After it expires you need to re-authenticate with username and

  password
* The `access_token` expires by default every hour, but also can be configurable by EverReal to

  have another expiration time (it is described by the `expires_in` property). Use the

  `refresh_token` to generate a new one if you get an unauthorized response

Bellow you can see some examples to get token correctly.

{% tabs %}
{% tab title="Bash" %}

```bash
curl --location --request POST 'https://{custom_subdomain}.everreal.co/accounts/oauth/token' \
--header 'Content-Type: application/json' \
--header 'Cookie: accept-language=de-DE' \
--data-raw '{ 
"username": "john.doe@everreal.co", 
"password": "Password", 
"client_id": "<Client_iD>", 
"client_secret": "<Client Secret>", 
"scope": "offline_access *", 
"grant_type": "password" 
}'
```

{% endtab %}

{% tab title="C#(RestSharp)" %}

```csharp
var client = new RestClient($"https://{custom_subdomain}.everreal.co/accounts/oauth/token");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Cookie", "accept-language=de-DE");
var body = @"{ 
" + "\n" +
@"""username"": ""john.doe@everreal.co"", 
" + "\n" +
@"""password"": ""Password"", 
" + "\n" +
@"""client_id"": ""<Client_iD>"", 
" + "\n" +
@"""client_secret"": ""<Client Secret>"", 
" + "\n" +
@"""scope"": ""offline_access *"", 
" + "\n" +
@"""grant_type"": ""password"" 
" + "\n" +
@"}";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
```

{% endtab %}

{% tab title="JS" %}

```javascript
var axios = require('axios');
var data = JSON.stringify({
  "username": "john.doe@everreal.co",
  "password": "Password",
  "client_id": "<Client_iD>",
  "client_secret": "<Client Secret>",
  "scope": "offline_access *",
  "grant_type": "password"
});

var config = {
  method: 'post',
  url: `https://{custom_subdomain}.everreal.co/accounts/oauth/token`,
  headers: { 
    'Content-Type': 'application/json', 
    'Cookie': 'accept-language=de-DE'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json

url = "https://{custom_subdomain}.everreal.co/accounts/oauth/token"

payload = json.dumps({
  "username": "john.doe@everreal.co",
  "password": "Password",
  "client_id": "<Client_iD>",
  "client_secret": "<Client Secret>",
  "scope": "offline_access *",
  "grant_type": "password"
})
headers = {
  'Content-Type': 'application/json',
  'Cookie': 'accept-language=de-DE'
}

response = requests.post(url, headers=headers, data=payload)

print(response.text)
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
&#x20;**client\_id** and **client\_secret** are parameter provided by EverReal
{% endhint %}

#### Oauth2.0 Authorization Code Flow

**Important!** Use the Authorization Code Flow in not trusted environments, like Web or Mobile app clients. Below are the necessary endpoints for the Authorization Code Flow.&#x20;

```
authorizationUri="https://${subdomain}.everreal.co/accounts/dialog/authorize"
accessTokenUri="https://${subdomain}.everreal.co/accounts/oauth/token"
tokenInfoUri="https://${subdomain}.everreal.co/accounts/api/tokeninfo?access_token={token}"
revokeTokenUri="https://${subdomain}.everreal.co/accounts/api/tokenrevoke?token={token}"
userInfoUri="https://${subdomain}.everreal.co/accounts/api/userinfo"
```

A basic next.js example can be over our github page <https://github.com/EverRealGMBH/everreal-nextjs-nextauth-oauth2-example>:

{% tabs %}
{% tab title="Next.js example" %}
Read more here: <https://next-auth.js.org/v3/configuration/providers#using-a-custom-provider>

```
{
  id: "everreal",
  name: "EverReal",
  type: "oauth",
  version: "2.0",
  scope: "offline_access *",
  params: { grant_type: "authorization_code" },
  accessTokenUrl: `https://${subdomain}.everreal.co/accounts/oauth/token`,
  requestTokenUrl: `https://${subdomain}.everreal.co/accounts/oauth/token`,
  authorizationUrl: `https://${subdomain}.everreal.co/accounts/dialog/authorize`,
  profileUrl: `https://${subdomain}.everreal.co/accounts/api/userinfo`,
  async profile(profile, tokens) {
    return {
       ...profile
    }
  },
  clientId: "provided by everreal",
  clientSecret: "provided by everreal"
}
```

{% endtab %}
{% endtabs %}

#### Refresh access\_token API endpoint

## Refresh token in case it expires

<mark style="color:green;">`POST`</mark> `https://{custom_subdomain}.everreal.co/accounts/oauth/token`

Refresh the `access_token` in case it expires

#### Headers

| Name         | Type   | Description        |
| ------------ | ------ | ------------------ |
| Content-Type | string | `application/json` |

#### Request Body

| Name | Type   | Description                                                                                                                                           |
| ---- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|      | string | <p>{<br>"grant\_type":"refresh\_token",<br>"client\_id": "{secret}",<br>"client\_secret": "{secret}",<br>"refresh\_token":"{refresh\_token}"<br>}</p> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
"access_token": "NEW TOKEN",
"expires_in": "3600" 
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Use the `access_token` to authenticate to any protected endpoint by passing it to the “Authorization” header like this: “Authorization: Bearer MY\_ACCESS\_TOKEN”
{% endhint %}

## User information

<mark style="color:blue;">`GET`</mark> `https://{custom_subdomain}.everreal.co/accounts/api/users/me`

Based on Bearer token provided in header request, it will retrieve user information and all information about it.

#### Headers

| Name          | Type   | Description        |
| ------------- | ------ | ------------------ |
| Content-Type  | string | `application/json` |
| Authorization | string | Bearer token       |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "id": "76dccab0-652e-4543-802c-7c701c098ad3",
    "email": "john.doe@ovooovo.com",
    "isActive": true,
    "firstName": null,
    "lastName": null,
    "profilePhoto": null,
    "profileData": {
        "language": "en-US"
    },
    "isTenant": false,
    "createdAt": "2021-07-19T14:21:50.215Z",
    "updatedAt": "2021-07-19T14:21:50.215Z",
    "areTermsAccepted": true,
    "companies": [
        {
            "id": "76dccab0-652e-4543-802c-7c701c0b3bb3",
            "name": "automation-reporting-qa",
            "isDefault": true
        }
    ],
    "currentCompany": {
        "id": "76dccab0-652e-4543-802c-7c701c0b3bb3",
        "name": "automation-reporting-qa",
        "partner": {
            "id": "76dccab0-652e-4543-802c-7c701c046579",
            "name": "test-documentation",
            "subdomain": "test-documentation"
        },
        "isDefault": true
    },
    "tokenInfo": {
        "audience": "76dccab0-652e-4543-802c-7c701c0a68f6",
        "scope": [
            "offline_access",
            "company_contracting_edit_contract",
            "message_templates_all",
            "company_portfolio_all",
            "company_user",
            "email_templates_all"
        ],
        "user_id": "76dccab0-652e-4543-802c-7c701c097b81",
        "expires_in": 3571
    }
}
```

{% endtab %}
{% endtabs %}


---

# 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://api-docs.everreal.co/master.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.