# 2FACE ## Introduction Welcome to the 2FACE RESTful API documentation. This documentation will help you get started with the service. If you have any questions you can use write us an email at to get in contact with us. ## Navigating the documentation 2FACE endpoints are organized by function. Each section contains an overview of the available endpoint, a description of configurable options, as well as an example of how to use them.

Function	Description	Quick Link
Session Management	Contains endpoints related to starting or closing sessions.	/pages/yGxq9GQFCxrgDbocuddh
Jobs	Contains endpoints related to jobs initiated by users or the manager.	/pages/VxJvZ4U4L0uKsKCLNnh6
Faces	Collection of endpoints related to face detection and recognition operations.	/pages/-MbisWZ8BjB0s7xxQJc8
Documents	Collection of endpoints related to document classification and data extraction operations.	/pages/a4ZQvSm4oDjuTzWnnbmb
Users	Collection of endpoints allowing search operations of users that have attempted a validation.	/pages/SDZBPC2iLoFwYQqakGAp
Attempts	Contains the endpoints that can be used to get the information of attempts and operate on them.	/pages/SDZBPC2iLoFwYQqakGAp

{% hint style="info" %} You can always import 2FACES API by using this [Postman Collection](https://api.postman.com/collections/16165301-1b548f34-2279-4a23-90c0-8f75fc8e24f2?access_key=PMAT-01HYH4F4F38MT14RECKH6S9RRP). {% endhint %} ## Authentication 2FACE's API provides two methods for authentication: #### App API Key This is the preferred authentication method for unattended production applications. API keys can be created and invalidated via the company applications admin panel and should be passed as an HTTP header using the **Authorization** key. #### Session Token Some endpoints require a valid and active session token instead of an API key. These tokens can be created with the endpoints in the ***Session Management** section* and should be passed as an HTTP header using the **X-Tagshelf-Session** key. {% content-ref url="/pages/yGxq9GQFCxrgDbocuddh" %} [Session Management](/2face-endpoints/session-management.md) {% endcontent-ref %} {% hint style="info" %} We recommend that you don't expose your api key in your client app. They are meant to be used from a backend server; session tokens, on the other hand, are safe to use in any environment. {% endhint %} *** ## Limiting To ensure fair usage and optimal performance of our API, we have implemented rate limiting measures. These limits help maintain stability and prevent abuse of the platform. Please take note of the following details: ### Overall Rate Limit You can make up to **2,500** API requests per minute. Authenticated requests are associated with the authenticated user, regardless of the used authentication method. This means that all requests authorized by a user share the same quota of **2500** requests per minute even if they authenticate with different tokens owned by the same user. ### Retry Limits on Specific Endpoints Starting from July 1st, 2023, we have introduced a new feature that includes a retry limit on certain endpoints. The affected endpoints are those beginning with `/documents` and `/faces`. When making requests to these endpoints, you will receive a response headers named * `x-attempt-limit` indicating the number of retries allowed. * `x-attempt-retries` indicating the number of retries remaining. Once you reach the retry limit, you must create a **new session** in order to keep using these endpoints. #### Example > Headers\ > `x-attempt-limit: 3` > > `x-attempt-retries: 2` > > This means that you can retry the request a maximum of 3 times if needed and you have 2 remaining retries. ### Why Retry Limits? The retry limits are implemented to enhance the stability and efficiency of our platform. They provide better control over retries, allowing you to manage your integration more effectively. If you need to make multiple requests to the affected endpoints, please ensure that you handle the retry limits appropriately. ### File Size Limiting You can upload files up to **10MB** in regular requests. *** ## User Agent All API requests **MUST** include a valid *User-Agent* header key-value pair. Requests without a valid User-Agent header will be rejected. We request that you use your TagShelf username, or the name of your application, for the User-Agent header key-value pair. This allows us to identify your API requests properly and contact you if there are problems. Here's an example: ``` User-Agent: Amazing-magical-App ``` cURL and Postman send a valid User-Agent header key-value pair by default. If you do not provide a valid User-Agent header via cURL (or via an alternative client), you will receive an HTTP status code **403** response. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://2face.tagshelf.dev/master.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.