# Ключевые понятия Oz API

Oz API обеспечивает полноценный REST API-интерфейс для биометрии лица: как сравнения лиц, так и Liveness-проверок. В этой статье описаны основные концепции Oz API.

### Аутентификация, роли пользователей и управление доступом

В целях безопасности каждый вызов Oz API требует наличия в заголовке токена доступа. Чтобы получить этот токен, вызовите метод `POST /api/authorize/auth` с полученными от нас логином и паролем. В ответе вы получите токен доступа. Его нужно будет указывать в заголовке `X-Forensics-Access-Token` во всех последующих вызовах методов Oz API. Подробнее процесс аутентификации описан [здесь](https://doc.ozforensics.com/oz-knowledge-ru/rukovodstva/rukovodstvo-razrabotchika/api/oz-api/autentifikaciya-i-obrabotka-dannykh/tokens).

Для пользователей системы есть набор ролей, различающихся по предоставляемым возможностям: от роли `CLIENT`, которая дает возможность проводить проверки и скачивать отчеты без прав администратора, до `ADMIN` с полным доступом практически ко всем объектам системы. Детальная информация по ролям находится [здесь](https://doc.ozforensics.com/oz-knowledge-ru/rukovodstva/rukovodstvo-razrabotchika/api/oz-api/user-roles).

### Сохранение данных

Основная сущность в Oz API – это папка (заявка): в папку вы можете загружать медиафайлы, запускать для них анализы и получать результаты не только для отдельных анализов, но и для папки в целом. В одной папке может быть любое количество медиафайлов, для каждого из которых можно назначить любое количество анализов. Анализы также могут назначаться для нескольких медиафайлов сразу.

<figure><img src="https://2041336905-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHLoHbtSPFA1Ul7oKM5SC%2Fuploads%2FBzSkG1Ml3SSqCYazBG1L%2Fer%20api%20basics%20New%20ru.drawio%20(1).svg?alt=media&#x26;token=c1caf3c8-9d59-4980-bc0e-77ce71957655" alt=""><figcaption></figcaption></figure>

### Типы медиафайлов и теги

Oz API работает и с фото-, и с видеофайлами. Видео при этом может быть как файлом в «обычном» понимании, то есть контейнером в формате MP4 или MOV, так и последовательностью кадров в ZIP-архиве. Чтобы определить тип медиафайла, Oz API использует MIME-тип файла.

Кроме типа файла, важно также понимать, что именно запечатлено на фото или видео: например, это может быть фотография лицевой стороны документа или селфи-видео, снятое человеком. Для описания содержания фото или видео используются теги, и на основе этих тегов система решает, какие анализы будут назначены для того или иного медиафайла. Наиболее часто используемые теги:

* `photo_id_front` – для лицевой стороны документа
* `photo_selfie` – для референтного фото, не являющегося документом
* `video_selfie_blank` – для Liveness-видео, снятого не средствами Oz Liveness SDK
* если фото или видео снято средствами нашего SDK, теги выставляются автоматически

### Асинхронные анализы

Поскольку анализ видео может занять несколько секунд, анализы проводятся асинхронно. Сначала вы запускаете анализ (`POST /api/folders/{{folder_id}}/analyses/`), а затем следите за результатами, периодически запрашивая их с сервера, пока обработка не закончится (`GET /api/analyses/{{analyse_id}}` для определенного анализа или `GET /api/folders/{{folder_id}}/analyses/` для всех анализов, назначенных на папку). Кроме того, можно использовать вебхуки. С примером опроса и использования вебхука можно ознакомиться [здесь](https://doc.ozforensics.com/oz-knowledge-ru/rukovodstva/rukovodstvo-razrabotchika/api/oz-api/use-cases/liveness).&#x20;

Более детальная информация о возможностях Oz API содержится в [соответствующей секции нашего руководства разработчика](https://doc.ozforensics.com/oz-knowledge-ru/rukovodstva/rukovodstvo-razrabotchika/api/oz-api).