End User Authentication

Authenticate the end-user

When Users are interacting with your product, and a request reaches your backend, you may want to validate that the relevant User is authenticated. For that purpose Copilot.cx exposes an API call that receives the end-user access token (in the body), and returns the End User ID, in case that token is valid.

As in every Management API requests, this call should include your management access token in the authentication header.

Url

POST https://<BASE_URL>/v2/api/management/copilot_connect/authenticate

Headers

Authorization: <TOKEN_TYPE> <ACCESS_TOKEN>
Content-Type: application/json

Note: The header contains your management authentication token, generated on the 'Session Management' chapter.

Body

{
  "access_token": "<END_USER_ACCESS_TOKEN_TYPE> <END_USER_ACCESS_TOKEN>"
}

Response

Success

{
  "is_token_valid": true / false,
  "to_client_response": <OBJECT_IN_CASE_OF_INVALID_TOKEN>,
  "user_id": "<USER_ID>",
  "user_role": "APPUSER"
}
Response Model - EndUserAuthenticationResponse
  • is_token_valid - (Boolean) Indicates whether the End User access token is valid.
  • user_id - The End User ID, in case that the token is valid. Otherwise, it will be null.
  • user_role - The role of the End User, in case the token is valid. For End Users it will return as "APPUSER". When the token is invalid it will return as null.

💡 In case the value "SERVICE_ACCOUNT" is returned in the user_role field, that would indicate you might have sent a valid Management access token, instead of an End User access token.

Failures

In case that the authentication header is missing or the management session has expired, the following error will return:

HTTP: HTTP/1.1 401 Unauthorized

{
  "reason": "AUTH.UNAUTHORIZED",
  "error_message": ""
}

In case of invalid response HTTP: HTTP/1.1 400 Bad Request

{
  "reason": "COMMON.REQUEST_VALIDATION",
  "error_message": "access token to authenticate must be provided on the body"
}

Example

Request

curl -X POST \
 'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/authenticate' \
 -d "{\"access_token\": \"Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IkFQUFVTRVIiLCJkZXZpY2VfaWQiOiJzdHJpbmciLCJ1c2VyX2lkIjoiNWM0ZWVkNmVmYWZlZjI0NWI0NWQxZWI2IiwiZXhwaXJhdGlvbl90aW1lIjoxNTUyODQ5Nzc5NTA4LCJqd3RWZXJzaW9uIjoiand0MSJ9.zE5uq8SUTewQxprxpD7E9YiEFMNMXN9UHv3bX3cyX8Y\"}" \
 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
 -H 'Content-Type: application/json'

Response

When an End User token is valid:

{
  "is_token_valid": true,
  "user_id": "5c4eed6efafef245b45d1eb6",
  "user_role": "APPUSER",
  "to_client_response": null
}

When an End User token is invalid

{
  "is_token_valid": false,
  "user_id": null,
  "user_role": null,
  "to_client_response": {
    "http_code": 401,
    "http_body": {
      "error_code": 401,
      "reason": "auth.unauthorized",
      "error_message": ""
    }
  }
}
← ThingCollect API →