External Authentication

Authorization

API

Initialize external authentication process

POST api/external-auth/init

Request

Field	Required	Type	Description
provider	✅	string	Authentication provider name (mock, esia)
processUuid	✅	string	External system process identifier
returnUrl	✅	string (url)	URL to return to after authentication process completion

Response

{
  "status": "ok",
  "timestamp": 1656576583000,
  "data": {
    "processUuid": "", // KYC authentication process identifier
    "provider": "esia", // Provider name
    "clientId": null, // Client ID to whom this process is attached (Set by a separate method)
    "redirectUrl": "" // Link for client redirect
  }
}

:::caution If an error occurs during authorization, KYC will redirect the client to returnUrl with errorCode and errorMessage parameters :::

Data Transfer

API

GET api/external-auth/{uuid}/fetch

where uuid - KYC authentication process identifier

Response

{
  "status": "ok",
  "timestamp": 1656575289000,
  "data": {
    "userOID": "", // User identifier in authentication provider
    "data": {} // Data received from provider mapped to core client object
  }
}

Client Creation

After client logs into authentication provider personal account

API

PUT api/external-auth/{uuid}/attach

where uuid - KYC authentication process identifier

Request

Field	Required	Type	Description
clientId	✅	numeric	Client ID from core

Response

{
  "status": "ok",
  "timestamp": 1656576583000,
  "data": {
    "processUuid": "", // KYC authentication process identifier
    "provider": "esia", // Provider name
    "clientId": null // Client ID to whom this process is attached (Set by a separate method)
  }
}

Scoring

Get authorization process by clientId

GET /api/external-auth/client/{clientId}

Request Params:

Field	Required	Type	Description
provider	❌	string(enum)	Provider name for filtering (esia, mock)
state	❌	string(enum)	Process status (pending, finished, failed)

TIP

Processes are returned in descending order by creation date.

Response:

{
  "status": "ok",
  "timestamp": 1692953997000,
  "data": [
    {
      "clientId": 353,
      "uuid": "96aa2533-4157-4bb6-86ba-56ca884de86e",
      "provider": "esia",
      "state": "finished",
      "userOid": "1000550149",
      "2factorAuthentication": "otp",
      "created_at": "2022-06-30T08:45:27.000000Z",
      "updated_at": "2022-06-30T09:09:35.000000Z"
    },
    {
      "clientId": 353,
      "uuid": "96a824aa-dd1e-4052-b279-e5cd583ea184",
      "provider": "esia",
      "state": "finished",
      "userOid": "1000299656",
      "2factorAuthentication": null,
      "created_at": "2022-06-29T08:52:18.000000Z",
      "updated_at": "2022-06-29T08:53:08.000000Z"
    },
    {
      "clientId": 353,
      "uuid": "9651ecaf-53a3-42d6-b003-f0dacfe15056",
      "provider": "mock",
      "state": "finished",
      "userOid": null,
      "created_at": "2022-05-17T12:14:34.000000Z",
      "updated_at": "2022-05-17T12:14:43.000000Z"
    }
  ]
}

:::caution For esia provider processes, the field 2factorAuthentication = tokenData.acr.2fa is added :::

Get authorization process by uuid

GET /api/external-auth/{uuid}

Response:

{
  "status": "ok",
  "timestamp": 1692953997000,
  "data": {
    "clientId": 353,
    "uuid": "96aa2533-4157-4bb6-86ba-56ca884de86e",
    "provider": "esia",
    "state": "finished",
    "userOid": "1000550149",
    "2factorAuthentication": "otp",
    "created_at": "2022-06-30T08:45:27.000000Z",
    "updated_at": "2022-06-30T09:09:35.000000Z"
  }
}