ESIA GATEWAY (1.0.0)

Download OpenAPI specification:Download

1. Введение

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

Все запросы должны отправляться по защищенному протоколу HTTPS на адрес https://api.esia.cloud/api/v1.

Параметры запроса передаются в теле сообщения. данные как в формате application/json, так и в формате x-www-form-urlencoded. Схема авторизации пользователей идентична протоколу OAuth 2.0

2.Схема работы

1) Пользователь нажимает ссылку "Войти через госуслуги"

2) Приложение отправляет запрос Authorization Request на сервер ЕСИА-облака

3) ЕСИА-облако отправляет пользователя на страницу авторизации ЕСИА

4) Пользователь вводит свой логин пароль, при необходимости проходит двухфакторную авторизацию. А также выдает разрешения запрашиваемые ИС.

5) ЕСИА-облако с помощью HTTP Redirect возвращает временный токен доступа

6) Приложение отправляет запрос с временный токеном и получает токен авторизации

7) Ответ содержит токен авторизации

3. Примеры запросов

Запрос кода авторизации #необходимо перенаправить браузер пользователя по адресу
https://api.esia.cloud/api/v1/ac?client_id=123ABC45&state=82bdcf89-1166-4bfe-905b-aaa2132537ec&code=code&redirect_uri=https%3A%2F%2Fyour-site.ru%2Fauth&scope=openid%20fullname
Обмен кода авторизации на access-token
 < ?php
    #необходимо выполнить post запрос с нужными параметрами с передачей code полученного на предыдущем шаге 
    $ch = curl_init('https://api.esia.cloud/api/v1/te');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, "client_id=123ABC45&client_secret=123456&state=124cfbba-4902-48c5-a4ca-ad339cc9b9f6&code=cf9e71891ffda3b23d259ee04733b08f8ed03cfd8757087be4b719ae33930f91a0e451117685f40e10f77255e5ec00b7f31c6472ad6a31411d45fcc17e377bcb&scope=openid%20fullname&redirect_uri=https%3A%2F%2Fyour-site.ru%2Fauth");
    $json = curl_exec($ch);
    curl_close($ch);
    echo $json; 
  ?>
   
Получение данных о пользователе
 < ?php
 $ch = curl_init('https://esia-cloud/api/v1/data/3456789');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  $headers = array("Authorization: Bearer d8c05c0d3fdac10ec86ce6fdf4eec7bca5d771510e5fbacca0d001e957f15c47f0eeeca864369d6b056d80689e8e7f4788670712755a4a29f8dde936024626a0");
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); 
  $json = curl_exec($ch);
  curl_close($ch);
  echo $json; 
  
  ?>
   
Выход из системы #необходимо перенаправить браузер пользователя по адресу
https://api.esia.cloud/api/v1/logout?client_id=123ABC45&redirect_uri=https%3A%2F%2Fyour-site.ru%2Fauth

4. Коды ошибок

Ошибки и их описание возвращаемые системой

  Коды ошибок
  | error  | error_description |
  | ------------- | ------------- |
  | invalid authorization  | отсутсвует HTTP заголовок Authorization Bearer |
  | invalid token or oid  | неверный token или oid  |
  | bad redirect_uri | некорректный redirect_uri |
  | invalid request | отсутсвует нужные параметры запроса |
  | invalid client_secret | неверный client_id или client_secret |
  | invalid code | отсутсвует, просрочен или неверный код авторизации |
  | invalid token | отсутсвует, просрочен или неверный токен |
  | invalid client | не удалось найти ИС |
  | bad redirect_uri | некорректный redirect_uri |
  | redirect_uri not exist | указанный в запросе redirect_uri отсутствует среди разрешенных для ИС |
  | collection not exist | запрошен несуществующий набор данных |
  | invalid esia token | Отсутсвует ЕСИА access-token. Сначала нужно запростить авторизационный код (code). |
 

Authentication

gw_auth

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: https://api.esia.cloud/api/v1/ac
Token URL: https://api.esia.cloud/api/v1/te
Scopes:
  • write -

    allows modifying resources

  • read -

    allows reading resources

api_key

Security Scheme Type API Key
Header parameter name: api_key

OAuth 2.0

Аутентификация и авторизация OpenID Connect 1.0

Получение авторизационного кода

Необходимо перенаправить браузер пользователя передав следующие параметры

Authorizations:
query Parameters
client_id
required
string

Идентификатор ИС в ЕСИА-облаке

code
required
string

Тип ответа, который ожидается от ЕСИА-облака, всегда имеет значение code

redirect_uri
required
string

Cсылка, по которой должен быть направлен пользователь после того, как даст разрешение на доступ

scope
required
string

Область доступа, запрашиваемые права. Полностью соответсвуют scope из методичиских рекомендаций ЕСИА

state
required
string

Набор случайных символов, необходимо для защиты от перехвата

Responses

Response samples

Content type
application/json
{
  • "code": "db144da9dbebe1a9755be8c8f65ed3521892901526d195ff561c17e23c93226c3e7faaa1c4faebd0137d786cb4949a48ee8799a395e1ba863cffb87d290b8219",
  • "state": "98779bc6-a803-472c-a6a2-fac467d1abb1"
}

Получение access_token в обмен на авторизационный код

Для получения кода доступа access_token отправьте следующие параметры

Authorizations:
query Parameters
client_id
required
string

Идентификатор ИС в ЕСИА-облаке

client_secret
required
string

API-ключ из Настроек личного кабинета

code
required
string

Значение авторизационного кода, который был ранее получен от ЕСИА и который необходимо обменять на access_token

grant_type
required
string

Всегда принимает значение authorization_code

redirect_uri
required
string

Cсылка, по которой должен быть направлен пользователь после аутентификации (то же самое значение, которое было указано в запросе на получение авторизационного кода)

scope
required
string

Область доступа, запрашиваемые права (то же самое значение, которое было указано в запросе на получение авторизационного кода). Полностью соответсвуют scope из методичиских рекомендаций ЕСИА.

state
required
string

Набор случайных символов, необходимо для защиты от перехвата

timestamp
required
string

Время запроса маркера в формате yyyy.MM.dd HH:mm:ss Z (например, 2011.10.25 12:27:21 +0900)

token_type
required
string

Всегда принимает значение Bearer

Responses

Response samples

Content type
application/json
{
  • "access_token": "d4551b5a1d8073d69c3b02aaf0ea5454bd4421276c4c8daf802c35f60d507ac0abcb60698c41039a47d312050030486025a321c0da3173fe51d306f9a4e337c7",
  • "refresh_token": "9d85c52a-5680-454d-969f-ce7b9fc646ca",
  • "id_token": "eyJ2ZXIiOjACBnR5cCI6IkpXVCIsInNidCI6ImlkIiwiYWxnIjoiR09TVDM0MTBfMjAxMl8yNTYifQ.eyJhdWQiOiIyMzUzMDQ4NjEiLCJzdWIiOjI0Mjg0ODU5MiwibmJmIjoxNjM1MzkyMDg5LCJhbXIiOiJQV0QiLCJ1cm46ZXNpYTphbWQiOiJQV0QiLCJhdXRoX3RpbWUiOjE2MzUzOTE0NL2-IlzcyI6Imh0dHA6XC9cL2VzaWEuZ29zdXNsdWdpLnJ1XC8iLCJ1cm46ZXNpYTpzaWQiOiI1ZTk0MTEzMC1kNWExLTQ3OTAtODE2YS05Yjg4NTY4ZGNlYzMiLCJ1cm46ZXNpYTpzYmoiOnsidXJuOmVzaWE6c2JqOnR5cCI6IlAiLCJ1cm46ZXPorTpzYmo6aXNfdHJ1Ijp0cnVlLCJ1cm46ZXNpYTpzYmo6b2lkIjoyNDI4NDg1OTIsInVybjplc2lhOnNiajpuYW0iOiIwNzYtMzQyLTI1MCA1OSJ9LCJleHAiOjE2MzU0MDI4ODksImlhdCI6MTYzNTM5MjA4OX0.BCLMauut1A8QpnFoQMIUwXvowFf-zRKil6fgQrDHhu50xoV0uS8lo4PoqgZpsCgTF6HWw6TaWgAlTpgPX7aeZA",
  • "oid": "12345678",
  • "token_type": "Bearer"
}

Выход из системы

Выход в рамках единой сессии ЕСИА

Authorizations:
query Parameters
client_id
required
string

Идентификатор ИС в ЕСИА-облаке

redirect_uri
string

Cсылка, по которой должен быть направлен пользователь после успешного логаута

Responses

Получение общих данных пользователей

Получение ФИО, даты рождения, СНИЛС, ФИО и прочих обобщенных данных по запрошенным скоупам. Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.

Authorizations:
path Parameters
oid
required
string

Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА

Responses

Response samples

Content type
application/json
{
  • "info": {
    }
}

Получение контактов пользователей

Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.

Authorizations:
path Parameters
oid
required
string

Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА

Responses

Response samples

Content type
application/json
{
  • "ctts": [
    ]
}

Получение списка адресов пользователей

Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.

Authorizations:
path Parameters
oid
required
string

Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА

Responses

Response samples

Content type
application/json
{
  • "addrs": [
    ]
}

Получение списка документов пользователей

Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.

Authorizations:
path Parameters
oid
required
string

Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА

Responses

Response samples

Content type
application/json
{
  • "docs": [
    ]
}

Получение списка детей пользователей

Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.

Authorizations:
path Parameters
oid
required
string

Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА

Responses

Response samples

Content type
application/json
{
  • "kids": [ ]
}

Получение списка автомобилей пользователей

Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.

Authorizations:
path Parameters
oid
required
string

Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА

Responses

Response samples

Content type
application/json
{
  • "vhls": [
    ]
}

Получение списка организаций пользователей

Для получения персональных данных о пользователях система-клиент должна направить соответствующий запрос. Для авторизации HTTP-запрос должeн содержать следующий заголовок: Authorization: Bearer <access_token>, где access_token — токен авторизации права на исполнение запрашиваемого метода с заданным набором параметров.

Authorizations:
path Parameters
oid
required
string

Внутренний идентификатор объекта, в том числе пользователя, в ЕСИА

Responses

Response samples

Content type
application/json
{
  • "orgs": [ ]
}