API Reference

The details of API endpoints for Web KYC.

get
Authenteq Identity Server

https://identity.authenteq.com/authorize
The Authenteq Identity Server OAuth endpoint is technically not an API. Rather, it directs the user to a page that starts the process of identity verification and on success, redirects the user back to the client service with a code as a parameter.
Request
Response
Request
Query Parameters
response_type
required
string
Defines the grant type. The only supported grant type is OAuth Authorization Code, so the value should be code
client_id
required
string
The clientId identifier assigned to the client.
redirect_uri
required
string
The redirect URI that will be used to pass the code back to the client service. It must match the URI stored in the client settings.
scope
required
string
The list of user properties you want to get from user details. Currently, the only supported value is kyc
state
required
string
A random string generated by the client application that will be passed back with the code. It should be stored in a session or a cookie.
back_url
optional
string
The URL for the Back to... link in the identity server.
Response
200: OK
Redirect to redirect_uri with code and state passed as parameters.
https://example.com/result?code=<...>&state=<...>

post
The Code to Token Exchange

https://api.authenteq.com/v2/web-kyc/token
The token endpoint that is used to exchange the code for the authorization token. The token is used to retrieve user details. The token is valid only for 15 minutes. After that time, user data is no longer accessible. There is no way to refresh or generate a new token.
Request
Response
Request
Body Parameters
grantType
required
string
Indicates the OAuth 2.0 grant type. It should be authorization_code
code
required
string
The authorization code received in the redirect URI params.
redirectUri
required
string
The redirect URI used to receive the code.
clientId
required
string
The identifier assigned to the client.
clientSecret
required
string
An alphanumeric string used for token exchange and retrieving user details.
Response
200: OK
Returns token that can be used to retrieve the user details.
{
"token": "<...>"
}

This endpoint should be called by your backend system.

The client secret, as its name suggests, is a secret and should never be made publicly available. It SHOULD NOT be stored in the frontend code that is run in the user's browser.

post
User Details

https://api.authenteq.com/v2/web-kyc/details
The endpoint returns the user details extracted from the user document during registration. The user data is paired with the authorization token.
Request
Response
Request
Headers
Authorization
required
string
The header that authorizes the request with the token. The value should have format: Bearer <token>
Response
200: OK
The details extracted from the user document.
{
portrait: "<base64_encoded_JPEG_image>",
selfie: "<base64_encoded_JPEG_image>",
croppedDocs: {
front: "<base64_encoded_JPEG_image>",
back: "<base64_encoded_JPEG_image>",
},
details:
{
documentNumber: "8136431812",
issuingCountry: "DEU",
documentType: "NID",
givenNames: "ANNA MARIA",
surname: "SCHMIDT",
dateOfBirth: "1987-01-12",
nationality: "DEU",
dateOfIssue: "2017-01-30",
dateOfExpiry: "2027-01-30",
sex: "F"
}
}

We keep user details for 72 hours to debug potential issues. After that time we remove them completely from our system.

Both portrait and selfie are Base64 encoded JPEG images of the user face. The first one is cropped from the ID, the second one is taken during the liveness process.

The croppedDocs field has two properties:

Property

Description

Mandatory

front

The base64 encoded JPEG image of the front page of the document.

Yes

back

The base64 encoded JPEG image of the back page of the document.

No

The details field of the response can hold following properties:

Property

Description

Mandatory

Example

documentNumber

Number of ID document.

Yes

"FG617451", "8136431812"

issuingCountry

Three letter country code in ISO 3166-1 alpha-3 format of the country which issued the ID.

Yes

"DEU", "UKR", "USA"

documentType

Document type described by abbreviations:

  • PP - passport,

  • DL - driver's license,

  • NID - national ID.

Yes

"PP", "DL", "NID"

givenNames

String with given names, separated by whitespace.

No

"ANNA MARIA DE O", "VITALII"

surname

String with surnames (family names), separated by whitespace.

No

"GARCIA DILS", "GOZHENKO"

nameSuffixes

String with name suffixes, separated by whitespace.

No

"JR 3RD", "8TH"

namePrefixes

String with name prefixes, separated by whitespace.

No

"DR MRS", "DR"

nationality

Three letter country code in ISO 3166-1 alpha-3 format of the user’s nationality.

No

"DEU", "UKR", "USA"

dateOfBirth

Date of birth.

No

"1987-01-12"

dateOfExpiry

Date of document expiration.

No

"2017-01-30"

dateOfIssue

Date when document was issued.

No

"2017-01-30"

sex

Gender of the user. Can contain one of values:

  • F - female,

  • M - male,

  • X - unspecified.

No

"F", "M", "X"

aml

Returns the result of Anti-Money Laundering database cross-check

No

Potential matches will be passed through in JSON with details