Generates an authentication token using the customer identifier and the deviceId. To use password-based authentication, the password option has to be enabled for the org. Contact the Product Support team to get a password enabled for your org.

Once the token is generated, you need to generate an OTP and validate the OTP to complete the authentication process. For password-enabled orgs, you need to verify the account for the first time.

When the token expires, you can regenerate it using token/regenerate.

Steps to generate token for mobile apps:
1. Generate a token using the token/generate API. You will get sessionId (valid for 15 minutes).
2. Using sessionId, generate an OTP.
3. Validate the OTP using sessionId. You will get the actual token along with the non-expiry key. You can configure and set expiry for this key. Refer to the documentation for more information.
4. Use the key to regenerate token whenever required.
Steps to generate token for Web application:
1. Generate a session using a token generate API. You will get VIEW token and sessionId (valid for 15 minutes).
2. Using sessionId, generate an OTP.
3. Validate the OTP using sessionId. You will get the actual token. The key is not generated for web applications.
4. Use the token generated for validating the OTP to regenerate the token.
Steps to generate token for password-based authentication:
1. For the first time user: * Use the steps mentioned above according to the type of application - mobile app or web app.
2. From second time:
  1. Generate a session using a token generate API. You will get VIEW token and sessionId (valid for 15 minutes).
  2. Validate the password (password/validate) using the sessionId generated.

Prerequisites

OTP must be enabled for the organization.
Daily OTP limit must be configured.
If using a password, password-based authentication must be enabled for the organization.
For mobile app logins, the device ID must be provided.

Resource Information


URI for Mobile App	/auth/v1/token/generate
URI for Web App	/auth/v1/web/token/generate
Rate Limited	Demo and testing clusters: 1000 requests per minute per API key. Other organizations: Rate limit is brand-specific.
Authentication	Not required
HTTP Method	POST
Batch Support	Yes

Request URL for mobile application

http://``{ae-host}``/auth/v1/token/generate

Request URL for web application

http://``{ae-host}``/auth/v1/web/token/generate

Example request

curl --location 'https://eu.api.capillarytech.com/auth/v1/token/generate' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'Cookie: _cfuvid=r0qUeHW4DtOxdgIN8.dJs77Xj15OkoCeaHRiplR4Qxs-1759834804501-0.0.1.1-604800000' \
--data '{
    "identifierType": "MOBILE",
    "identifierValue": "919999999993",
    "brand": "DocDemo",
    "deviceId": "123456785"
}'

curl --location 'https://eu.api.capillarytech.com/auth/v1/token/generate' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'Cookie: _cfuvid=r0qUeHW4DtOxdgIN8.dJs77Xj15OkoCeaHRiplR4Qxs-1759834804501-0.0.1.1-604800000' \
--data '{
    "identifierType": "MOBILE",
    "identifierValue": "919999999991",
    "brand": "DocDemo",
    "deviceId": "123456785",
    "password" : "abc123",
    "confirmPassword" : "abc123"
}'

curl --location 'https://eu.api.capillarytech.com/auth/v1/web/token/generate' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'Cookie: _cfuvid=dx9m0omOPswla2ni.yXNOV.9_4qHLCcfMI_vqjitSvU-1759835382650-0.0.1.1-604800000; _cfuvid=r0qUeHW4DtOxdgIN8.dJs77Xj15OkoCeaHRiplR4Qxs-1759834804501-0.0.1.1-604800000' \
--data-raw '
{
  "identifierType": "EMAIL",
   "identifierValue": "[email protected]",
    "brand": "DocDemo"
}
'

curl --location 'https://eu.api.capillarytech.com/auth/v1/web/token/generate' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'Cookie: _cfuvid=dx9m0omOPswla2ni.yXNOV.9_4qHLCcfMI_vqjitSvU-1759835382650-0.0.1.1-604800000; _cfuvid=r0qUeHW4DtOxdgIN8.dJs77Xj15OkoCeaHRiplR4Qxs-1759834804501-0.0.1.1-604800000' \
--data-raw '
{
  "identifierType": "EMAIL",
   "identifierValue": "[email protected]",
    "brand": "DocDemo",
    "password" : "abc123",
    "confirmPassword" : "abc123"
}
'

Body parameters

Parameter	Datatype	Description
identifierType*	enum	Identifier used for token generation. Values: MOBILE, EMAIL, USERNAME.
identifierValue*	string	Value of the specified identifierType.
deviceId*	string	Unique ID of the device from which the customer has generated the token.
brand*	string	Name of the brand or org for which authentication needs to be verified.
mobile**	string	Mobile number of the customer. Either the mobile number or email ID is required to authenticate with a username.
email**	string	Email ID of the customer. Either the mobile number or email ID is required to authenticate with a username.
password**	string	Password to log in to the app. Currently, there is no minimum or maximum character limit, and using special characters is not mandatory.
confirmPassword**	string	Reenter the password.

Parameters marked with * are mandatory, and parameters with ** indicate that either mobile or email is required for authentication with a username.

Example response

{
  "status": {
    "success": true,
    "code": 200,
    "message": "SUCCESS"
  },
  "auth": {
    "token": "eyJpZHYiOlsiTU9CSUxFfDkxOTk5OTk5OTk5MyJdLCJkZXYiOiIxMjM0NTY3ODUiLCJvcmciOiJET0NERU1PIiwiYWxnIjoiSFMyNTYifQ.eyJpc3MiOiJDQVBJTExBUlkgVEVDSE5PTE9HSUVTIiwib2djIjpbIjEwMDczN3xuZWVyYWouZG9jIl0sImV4cCI6MTc1OTgzOTMzNSwiaWF0IjoxNzU5ODM1NzM1LCJyb2wiOiJWSUVXIn0.8gRfA0CdBjYuSLtNJwREvmYqaAtk9C0Zm-b_-gUqPNQ",
    "key": null
  },
  "user": {
    "appRegistered": false,
    "sessionId": "P-6ec5fcc9-2bca-4778-9672-4ee5097d8313",
    "role": "VIEW",
    "userRegisteredForPassword": true
  }
}

{
  "status": {
    "success": true,
    "code": 200,
    "message": "SUCCESS"
  },
  "auth": {
    "token": "eyJpZHYiOlsiTU9CSUxFfDkxOTk5OTk5OTk5MSJdLCJkZXYiOiIxMjM0NTY3ODUiLCJvcmciOiJET0NERU1PIiwiYWxnIjoiSFMyNTYifQ.eyJpc3MiOiJDQVBJTExBUlkgVEVDSE5PTE9HSUVTIiwib2djIjpbIjEwMDczN3xuZWVyYWouZG9jIl0sImV4cCI6MTc1OTg0MTQxOSwiaWF0IjoxNzU5ODM3ODE5LCJyb2wiOiJWSUVXIn0.e1bltp_Tl7v4lBe0wRDH75NEPqmBcJBfZmFMdX9K-5s",
    "key": null
  },
  "user": {
    "appRegistered": false,
    "sessionId": "P-4b9437d5-38fe-4252-9628-9960f9b221f8",
    "role": "VIEW",
    "userRegisteredForPassword": false
  }
}

{
  "status": {
    "success": true,
    "code": 200,
    "message": "SUCCESS"
  },
  "auth": {
    "token": "eyJpZHYiOlsiRU1BSUx8Y2FwdGVzdEBnbWFpbC5jb20iXSwiZGV2IjpudWxsLCJvcmciOiJET0NERU1PIiwiYWxnIjoiSFMyNTYifQ.eyJpc3MiOiJDQVBJTExBUlkgVEVDSE5PTE9HSUVTIiwib2djIjpbIjEwMDczN3xuZWVyYWouZG9jIl0sImV4cCI6MTc1OTgzODgyNSwiaWF0IjoxNzU5ODM4NzM1LCJyb2wiOiJWSUVXIn0.2r1IueohKRA5dUmcWL23Ue1dCbcRDCrTKmaZGdPKABU",
    "key": null
  },
  "user": {
    "appRegistered": false,
    "sessionId": "P-a7f12cf8-8f64-4d74-87c1-644fdf67ef58",
    "role": "VIEW",
    "userRegisteredForPassword": true
  }
}

{
  "status": {
    "success": true,
    "code": 200,
    "message": "SUCCESS"
  },
  "auth": {
    "token": "eyJpZHYiOlsiRU1BSUx8Y2FwX3Rlc3R0b2tlbmdlbkBnbWFpbC5jb20iXSwiZGV2IjpudWxsLCJvcmciOiJET0NERU1PIiwiYWxnIjoiSFMyNTYifQ.eyJpc3MiOiJDQVBJTExBUlkgVEVDSE5PTE9HSUVTIiwib2djIjpbIjEwMDczN3xuZWVyYWouZG9jIl0sImV4cCI6MTc1OTgzOTM5MywiaWF0IjoxNzU5ODM5MzAzLCJyb2wiOiJWSUVXIn0.t38TrWnszJrlEo2E4Amq91O54VOe7CED-OOQkNjK80w",
    "key": null
  },
  "user": {
    "appRegistered": false,
    "sessionId": "P-99bfa3b8-10bf-4f39-a705-333bd1ca10d1",
    "role": "VIEW",
    "userRegisteredForPassword": false
  }
}

Response parameters

Parameter	Type	Description
status	Object	Contains response status information.
.success	Boolean	Indicates whether the operation was successful.
.code	Integer	Response status code. Example: 200
.message	String	Status message Example: SUCCESS
auth	Object	Contains authentication details.
.token	String	Authentication token generated for the session.
.key	String	Authentication key used for token regeneration.
user	Object	Contains user-specific information.
.appRegistered	Boolean	Indicates whether the user has registered for the mobile application
.sessionId	String	Unique session identifier that is valid for 15 minutes. This session ID is used for subsequent OTP generation and validation steps
.role	String	User's current role/permission level. Example: VIEW
.userRegisteredForPassword	Boolean	Indicates whether the user has registered for password-based authentication

Error code

Code	Description
1504	Unsupported brand