> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datanumia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and authorization

## Encryption

Datanumia Home API is secured with TLS 1.2.

## Rate limiting

The Home API implements a process for limiting and preventing excessive requests in accordance with RFC 6585. API users that regularly hit and ignore rate limits will be blocked from the platform. Get in touch with your Customer Success Manager to get more details about rate limiting and max file sizes.

## Authorization

### Home platform and OAuth2

Authorization within the Home platform is supported through the OAuth2 framework.

| OAuth2 role | Description | Home platform |
| - | - | - |
| Resource Owner | Entity that can grant access to a protected resource. Typically, this is the end-user | In the Home platform, it can be a Person or a Customer |
| Resource Server | Server hosting the protected resources | This is the Home API |
| Client | Application requesting access to a protected resource on behalf of the Resource Owner | This is the application you are developing which calls the Home API |
| Authorization Server | Server that authenticates the Resource Owner and issues access tokens after getting proper authorization | It is the Home platform authorization server |

Authorization with the Home API is done using an OAuth2 bearer token. It is performed with the Authorization HTTP header. Example:

```
Authorization: Bearer tkNYXgMl6h2OwykChw
```

OAuth2 enables application developers to build applications (Client in the OAuth2 terminology) that utilize authentication and data from the Home platform API.

Home supports the following flows:

| Flow/use case | associated grant type |
| - | - |
| machine to machine use cases | client credentials |

### Access token expiration

An access token expires 10 minutes after being delivered.
Once an access token expires, the Home platform will return 401 HTTP status code. A new one must be requested to keep using the Home platform.

### Refresh token

The Home platform does not support refresh tokens.

### Resource access using OAuth2

#### Register your application in the Home platform

Refer to the corresponding section in the [Product configuration](/docs/DeveloperTools/APIReference/03-product-configuration) section.

#### As a machine: Server-to-Server communication

As a Customer (Resource Owner in the OAuth2 terminology), you can access all the resources of your end users in a machine to machine use case through the OAuth2 client credentials flow. It is used:

* to manage the lifecycle of person, site and service offer objects within your scope as a customer
* to execute mass processing on all data within your scope

The recommendations defined in the RFC 6749, section 2.1 client types, must be considered carefully.

Applications (Client in the OAuth2 terminology) using the client credentials flow are considered by the Home platform as confidential clients.

Extract of the RFC 6749 with regard to confidential clients: [https://datatracker.ietf.org/doc/html/rfc6749#section-2.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1)

```
  confidential
      Clients capable of maintaining the confidentiality of their
      credentials (e.g., client implemented on a secure server with
      restricted access to the client credentials), or capable of secure
      client authentication using other means.
```

In other words, always be super extra very careful with your client\_id and client\_secret. Do not store them with source code!

Client Credentials Access Token Request

```
curl -X POST \
  'https://<HOME_PLATFORM_URI>/authorization-server/oauth/token?grant_type=client_credentials' \
  -H 'authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=' \
  -H 'content-type: application/x-www-form-urlencoded'
```

Client Credentials Access Token Response

```
{
  "access_token": "6qrZcUqja7812RVdnEKjpzOL4CvHBFG",
  "token_type": "Bearer",
  "expires_in": 604800,
  "scope": "home_elec_consumptions:read home_profiles:read"
}
```