Ejento API Access Guide

Overview

This guide outlines the steps required to authenticate and integrate with Ejento's APIs. Users must follow the authentication process to obtain access tokens, which are necessary for making API requests.

Authentication Process

To access Ejento’s APIs, users must complete the following steps:

1. Register on the Authentication App

   Use the registration API to create an account.

   Endpoint:

   POST https://{your_authentication_server}/api/users/signup

   Sample Request (JSON):

   {
     "email": "test@example.com",
     "password": "stringst",
     "full_name": "test example"
   }

   Notes:

   No explicit header is required for this API.

2. Login and Obtain Tokens

   Authenticate with your credentials to receive two types of tokens:
   (i) Authentication App Access Token — Used for token refresh and to call all Authentication APIs.
   (ii) Ejento Access Token — Used to access all Ejento APIs.

   Endpoint:

   POST https://{your_authentication_server}/api/login/access-token

   Sample Request (x-www-form-urlencoded):

   username: test@example.com  
   password: stringst  

   Notes:

   No explicit header is required for this API.

   Response:

   • Authentication App Access Token
   • Ejento Access Token

3. Refresh Access Token

   • Both tokens have an expiry period.
   • When tokens expire, you can generate new ones by calling the Refresh Token API, passing the Authentication App Access Token in the Authorization header as a Bearer Token.

   Endpoint:

   POST https://{your_authentication_server}/api/users/refresh-access-token

   Sample Request:

   • No request body is required.
   • Pass the current Authentication App Access Token in the header:

     Authorization: Bearer <current_auth_access_token>

   Response:

   • New Authentication App Access Token
   • New Ejento Access Token

---

Important Usage Notes:

• For all Authentication APIs, you must pass the Authentication App Access Token in the Authorization header as a Bearer Token.
• For all Ejento APIs, you must pass the Ejento Access Token in the Authorization header as a Bearer Token.
• Always use the appropriate token depending on which API you are accessing.

---

Using Ejento APIs

Once authenticated, users can access Ejento’s APIs. Detailed endpoint documentation is available at docs.ejento.ai.

API Base URL

https://{your_server_name}

Authorization Requirement

All API requests should include the Ejento Access Token as the authorization type Bearer Token in the request header.

API Endpoints

1. Create New Chat Thread

• Endpoint: POST /api/agent/{agent_id}/chat-thread
• Usage: Initiates a new chat thread.

2. Create Agent Response

• Endpoint: POST /api/agent/{agent_id}/response
• Usage: Provides agent responses.
• Important: Use the id field from the Create Chat Thread response as chat_thread_id in Create Agent Response to maintain the session.

---

Using Authentication APIs

Authorization Requirement

All API requests should include the Authentication App Access Token as the authorization type Bearer Token in the request header.

Read All Users

Retrieve the list of registered users:

curl -X 'GET' 
  'https://{your_authentication_server}/api/users/?skip=0&limit=100' 
  -H 'accept: application/json' 
  -H 'Authorization: Bearer <token>'

Note:
Replace {your_authentication_server} with your actual authentication server URL in all API requests.
Ensure you are using the correct server endpoint configured for your environment.

Update User Information

1. Update Any User (Global Admin Only)

Endpoint

PATCH https://{your_authentication_server}/api/users/{user_id}

Important Usage Note:

• This endpoint is strictly reserved for Global Admins.
• The API will only work when called with a valid Global Admin's Access Token passed in the Authorization header as a Bearer Token.
• If you try to call this API using a regular user's token, the request will be rejected.
• It allows Global Admin to update user information, including resetting or changing any user's password, by specifying the user's unique user_id as path parameter.
• The request must include a JSON-formatted body with the fields as shown in the example below.
• Regular users do not have access to this endpoint for updating their own details.

Example Request

curl -X 'PATCH' 
  'https://{your_authentication_server}/api/users/<user_id>' 
  -H 'accept: application/json' 
  -H 'Authorization: Bearer <token>' 
  -H 'Content-Type: application/json' 
  -d '{
    "email": "exampleuser@example.com",
    "is_active": true,
    "is_superuser": false,
    "full_name": "Pro Dev",
    "password": "stringst"
  }'

---

2. Change Own Password (For Authenticated Users)

Endpoint

PATCH https://{your_authentication_server}/api/users/me/password

Usage Instructions:

• This endpoint is used by authenticated users to change their own password.
• The request body must include both of the following fields in JSON format:
  • "current_password" — The user's existing password (for verification).
  • "new_password" — The new password the user wants to set.

Example Request

curl -X 'PATCH' 
  'https://{your_authentication_server}/api/users/me/password' 
  -H 'accept: application/json' 
  -H 'Authorization: Bearer <token>' 
  -H 'Content-Type: application/json' 
  -d '{
    "current_password": "your_current_password",
    "new_password": "your_new_password"
  }'

---

User Registration & Authentication Guidelines

• User Registration:

  • Every user must be registered using the API.
  • No other registration methods are available.

• Password Management:

  • You are responsible for securely storing user passwords.
  • Passwords do not expire, but access tokens expire after 2 days by default.
  • Use the refresh token API to generate new tokens without forcing users to re-login frequently.

• Token Generation:

  • Each user requires a unique access token for API interaction.
  • Tokens must be included in every API request for authentication.

• Credential Storage:

  • Login requires both an email and password.
  • Secure storage of credentials is essential for user authentication.

---

By following this guide, users can successfully authenticate, register, and interact with Ejento’s APIs. For more details, visit docs.ejento.ai.

---