> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/autenticacion.md).

# Autenticação

Os endpoints da Middleware API v2 são autenticados com um **token JWT do consumer** enviado no cabeçalho `Authorization: Bearer <token>`. O token é emitido com base nos dois conceitos apresentados em [Middleware API v2](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2.md): a **plataforma do cliente** emite tokens para seus **consumers**, e cada chamada operacional é realizada em nome de um consumer.

### Cabeçalhos de identificação

| Cabeçalho          | Descrição                                                                                                         |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `platform-id`      | Identifica a plataforma do cliente. Obrigatória somente na emissão do token de consumer (`POST /consumer/token`). |
| `platform-api-key` | API key da plataforma do cliente. Obrigatória somente na emissão do token de consumer (`POST /consumer/token`).   |
| `consumer-id`      | Identifica o canal/consumer. Obrigatória em todos os endpoints operacionais.                                      |

### Requisitos dos endpoints operacionais

Todos os endpoints operacionais da Middleware API v2 exigem:

* **Autenticação OAuth2**: cabeçalho `Authorization: Bearer <token>`, obtido por meio de `POST /consumer/token` (JWT assinado com RS256, veja abaixo).
* Cabeçalho **`consumer-id`**: identificador do consumer. Obrigatória e não pode estar vazia.
* Cabeçalho **`operation-id`**: identificador da [operação](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/operations.md) à qual pertencem os assets referenciados, conforme retornado por `POST /operation`. Obrigatória em qualquer endpoint cuja solicitação faça referência a assets armazenados, e sempre em [Document Validation](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation.md), que aceita apenas referências.

{% hint style="info" %}
A Middleware API v2 não utiliza autenticação por `x-api-key`. O esquema é OAuth2 Bearer + `consumer-id` (e `operation-id` nas solicitações que fazem referência a assets armazenados).
{% endhint %}

## Obter o token de consumer

Antes de invocar qualquer endpoint operacional, o consumer deve obter um token JWT e enviá-lo no cabeçalho `Authorization: Bearer <token>`. O token é emitido pela Facephi e inclui o `consumer-id` e os escopos correspondentes aos serviços habilitados para esse consumer.

### Endpoint

```
POST /consumer/token
```

### Cabeçalhos

| Nome                 | Tipo   | Obrigatório | Descrição                               |
| -------------------- | ------ | ----------- | --------------------------------------- |
| **platform-id**      | string | **Sim**     | Identificador da plataforma do cliente. |
| **platform-api-key** | string | **Sim**     | API key da plataforma do cliente.       |

### Corpo da solicitação

**Content-Type:** `application/json`

#### Parâmetros

| Parâmetro    | Tipo   | Obrigatório | Descrição                                                                       |
| ------------ | ------ | ----------- | ------------------------------------------------------------------------------- |
| `consumerId` | string | **Sim**     | Identificador do consumer (canal ou vertical) para o qual o token é solicitado. |

#### Exemplo de solicitação

```json
{
  "consumerId": "<consumerId>"
}
```

### Respostas

#### `200` Sucesso

#### Parâmetros de resposta

| Parâmetro    | Tipo   | Descrição                                                             |
| ------------ | ------ | --------------------------------------------------------------------- |
| `consumerId` | string | Consumer para o qual o token foi emitido.                             |
| `token`      | string | Token JWT a ser enviado no cabeçalho `Authorization: Bearer <token>`. |
| `expiresAt`  | string | Data e hora de expiração do token no formato **ISO 8601**.            |

#### Exemplo de resposta

```json
{
  "consumerId": "<consumerId>",
  "token": "<jwt>",
  "expiresAt": "2026-06-26T13:00:00.000Z"
}
```

{% hint style="info" %}
O token tem **validade de 1 hora** a partir da emissão (o instante exato da expiração é retornado no campo `expiresAt`). Após expirar, basta solicitar um novo pelo mesmo endpoint. Em cada solicitação, são validados a assinatura, o emissor, o `consumer-id`, a expiração e os escopos do token.
{% endhint %}
