> ## Documentation Index
> Fetch the complete documentation index at: https://x-lab.help/llms.txt
> Use this file to discover all available pages before exploring further.

# API-ключи

> Как открыть API-ключи, создать ключ, скопировать секрет и задать описание.

В **API-ключах** лаборатория выдаёт ключ, по которому внешняя программа обращается к данным от имени организации. Секрет показывается один раз, сразу после создания.

> [!NOTE]
>
> Экран доступен сотруднику, которому администратор разрешил **Управление ключами API**.

## Открытие API-ключей

В левом меню откройте **Настройки** и в группе **Доступ** нажмите **API-ключи**.

Кнопки в одной строке с заголовком **API-ключи**.

| Кнопка | Когда её используют |
| - | - |
| **К разделам** | Открывает **Настройки**. |
| **Создать** | Сразу создаёт ключ и открывает окно **API-ключ**, в котором секрет ещё можно скопировать. |

### Колонки таблицы

| Колонка | Что показывает |
| - | - |
| **Описание** | Пояснение, для какой программы выдан ключ. |
| **Идентификатор клиента** | Открытая часть ключа. |
| **Создан** | Дата и время создания. |

Двойной щелчок и карандаш открывают окно **API-ключ**. В строке доступна корзина.

![Русский интерфейс, светлая тема: Колонки Описание, Идентификатор клиента и Создан](https://mintcdn.com/x-lab/_ZXJSKEnqkRqUpoN/images/ru/lims/settings-api-keys/list.png?fit=max\&auto=format\&n=_ZXJSKEnqkRqUpoN\&q=85\&s=c53358201eed7a237c5708b67e762d9b)

Колонки **Описание**, **Идентификатор клиента** и **Создан**.

## Создание ключа

Нажмите **Создать**. Программа создаёт ключ и открывает окно **API-ключ**.

В окне сразу после создания три поля. **Идентификатор клиента** только для чтения. **Секрет клиента** тоже только для чтения, справа у него кнопка **Копировать секрет**. В **Описание** укажите, какая система будет использовать ключ, например **Вымышленная система «Лаборатория-Пример»**. Это только пояснение в списке ключей и не включает отдельную интеграцию.

Скопируйте секрет, пока окно открыто. После **Сохранить** поле секрета больше не показывается. Уже сохранённый ключ открывается без секрета: остаётся описание.

Внизу окна кнопки **Сохранить** и **Закрыть**. Если описание изменено и окно закрывают, программа открывает окно **Подтверждение** с текстом «Есть несохранённые изменения. Закрыть без сохранения?». **Да** закрывает окно и отбрасывает правку описания. **Нет** оставляет окно открытым. Сам ключ к этому моменту уже создан.

### Копирование секрета

Нажмите **Копировать секрет**.

> [!TIP]
>
> Программа отображает сообщение «Секрет скопирован.».

> [!NOTE]
>
> Если копировать **нечего**, программа отображает сообщение «Нечего копировать.».

### Сохранение описания

Нажмите **Сохранить**.

> [!TIP]
>
> Программа отображает сообщение «API-ключ сохранён.».

## Использование ключа для входа в API

Идентификатор и секрет клиента нужны, чтобы получить токен доступа. Секрет клиента не является токеном и не передаётся в запросах к данным. Сначала программа получает токен методом OAuth 2.0 **client\_credentials**, затем отправляет его в заголовке `Authorization: Bearer`.

Запрос токена отправляйте на рабочий API: `https://api.x-lab.pro/token`.

Тело запроса имеет тип `application/x-www-form-urlencoded` и содержит `grant_type=client_credentials`, `client_id` и `client_secret`. Успешный ответ содержит `access_token`, `token_type` и `expires_in`. Обновить такой токен через `/refresh` нельзя: после истечения срока получите новый по тем же client credentials.

> [!WARNING]
>
> Храните секрет клиента в защищённом хранилище на сервере интеграции. Не встраивайте его в браузерный код, мобильное приложение или публичный репозиторий. Если секрет стал известен посторонним, удалите этот ключ и создайте новый.

### Пример запроса через cURL

В примере переменные `X_LAB_CLIENT_ID` и `X_LAB_CLIENT_SECRET` уже заданы в окружении процесса.

```bash theme={null}
curl --request POST 'https://api.x-lab.pro/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=$X_LAB_CLIENT_ID" \
  --data-urlencode "client_secret=$X_LAB_CLIENT_SECRET"
```

В ответе найдите `access_token`. Передайте его в заголовке каждого запроса к защищённому API-методу. Например, запрос к коллекции `Company`:

```bash theme={null}
curl 'https://api.x-lab.pro/webapi/Company' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Accept: application/json'
```

`ACCESS_TOKEN` в этом примере — значение `access_token` из ответа сервера авторизации. Не отправляйте `client_secret` в запросе к `Company`.

### Пример на C\#

Пример получает токен, затем использует его для запроса к API. Переменные `clientId` и `clientSecret` загрузите из защищённой конфигурации интеграции.

```csharp theme={null}
using System.Collections.Generic;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System;
using System.Text.Json.Serialization;

var apiBaseUrl = "https://api.x-lab.pro";
using var http = new HttpClient();

using var tokenResponse = await http.PostAsync(
    $"{apiBaseUrl}/token",
    new FormUrlEncodedContent(new Dictionary<string, string>
    {
        ["grant_type"] = "client_credentials",
        ["client_id"] = clientId,
        ["client_secret"] = clientSecret
    }));

tokenResponse.EnsureSuccessStatusCode();
var token = await tokenResponse.Content.ReadFromJsonAsync<TokenResponse>()
    ?? throw new InvalidOperationException("Ответ без токена.");

using var request = new HttpRequestMessage(HttpMethod.Get, $"{apiBaseUrl}/webapi/Company");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();

public sealed record TokenResponse(
    [property: JsonPropertyName("access_token")] string AccessToken,
    [property: JsonPropertyName("token_type")] string TokenType,
    [property: JsonPropertyName("expires_in")] int ExpiresIn);
```

Атрибуты `JsonPropertyName` связывают свойства `TokenResponse` с точными именами полей в OAuth-ответе.

API проверяет ключ и выпускает токен для организации, которой принадлежит ключ. Доступ к конкретным методам определяется правилами API. Сервисные ключи используют для серверных интеграций; браузерная авторизация сотрудника выполняется другим способом.

## Удаление ключа

Корзина открывает окно **Подтверждение** с текстом «Удалить API-ключ?». **Да** удаляет ключ. **Нет** оставляет его.

> [!WARNING]
>
> Удалённый ключ вернуть на этом экране нельзя. Программа, которая им пользовалась, доступ потеряет.

## Если действие не выполнилось

Если список не открылся, программа отображает сообщение «Не удалось загрузить API-ключи.».

Если ключ не создался, программа отображает сообщение «Не удалось создать API-ключ.». Окно при этом не открывается.

Если секрет не попал в буфер обмена, программа отображает сообщение «Не удалось скопировать в буфер обмена.».

Если описание не записалось, программа отображает сообщение «Не удалось сохранить API-ключ.».

Если удаление не прошло, программа отображает сообщение «Не удалось удалить API-ключ.».

Если причину не устранить, спросите системного администратора.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.