Authentication
Start authentication
The POST /v3/ftn/auth endpoint is used to start an authentication using FTN.
POST /v3/ftn/auth
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
{
"refId": "12398698",
"redirectUrl": "https://..."
}
| Parameter | Required | Description |
|---|---|---|
| requestEmail | No | (BETA) If set, will request the e-mail address of the authenticated user. The functionality needs to be enabled for your company. Contact support to enable requestEmail. |
| requestPhone | No | (BETA) If set, will request the phone number of the authenticated user. The functionality needs to be enabled for your company. Contact support to enable requestPhone. |
| requestAddress | No | (BETA) If set, will request the address of the authenticated user. The functionality needs to be enabled for your company. Contact support to enable requestAddress. |
| refId | No | Reference ID which will be included in a Collect and in the redirect. |
| redirectUrl | No | Custom redirect URL, must be whitelisted. |
Response:
IDkollen will respond with HTTP status 201 for successful request, or 4xx/5xx on errors. For more information about errors, please see the Errors section.
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "PENDING",
"url": "https://..."
}
| Property | Description |
|---|---|
| id | Authentication id, used to cancel or get the status of this authentication request. |
| refId | The refId given in the request, if any. |
| url | The URL where the end user can identify themselves. |
Code redirect:
Once the end user has authenticated, they will be redirected to the redirect URL provided to IDkollen by you, including the very same "id" as a request parameter that can be used in the Collect step. If the parameter "refId" was used in the request, it will also be included as a request parameter.
https://your.redirect.url/?id=1668b9da-bff1-4dfc-ad48-60507b5a8d12&refId=12398698
A whole domain may also be whitelisted and sent with each request, but must for security reasons be whitelisted first. Multiple domains may be whitelisted. Please provide your whitelisted URLs by emailing us at support@idkollen.se.
Fetch result
The GET /v3/ftn/auth/{{id}} endpoint is used to check the status of an auth request.
NOTE: This endpoint is rate limited to one request per second.
GET /v3/ftn/auth/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
This endpoint will respond with a HTTP status of 404 if the authentication session has expired.
The status of an authentication can be either one of: PENDING, COMPLETED or FAILED.
Pending
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "PENDING"
}
| Parameter | Description |
|---|---|
| refId | The refId given in the request, if any. |
Completed
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "COMPLETED",
"ssn": "YYYYMMDDXXXX",
"name": "Firstname Lastname",
"givenName": "Firstname",
"surname": "Lastname",
"birthDate": "1908-09-29",
"email": "E-mail",
"phone": "Phone number",
"address": "Address"
}
| Parameter | Description |
|---|---|
| refId | The refId given in the request, if any. |
| ssn | A Finnish personal identification number to be used to complete the transaction. |
| name | The full name of the authenticated user. |
| givenName | The given name of the authenticated user. |
| surname | The surname of the authenticated user. |
| birthDate | The birth date of the authenticated user. |
(BETA) An e-mail address of the authenticated user. May be null if requestEmail was unset, if no such data is available, or if the user declined to share it. | |
| phone | (BETA) A phone numer of the authenticated user. May be null if requestPhone was unset, if no such data is available, or if the user declined to share it. |
| address | (BETA) An address of the authenticated user. May be null if requestAddress was unset, if no such data is available, or if the user declined to share it. |
Failed
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "FAILED",
"error": "INVALID_ID"
}
| Parameter | Description |
|---|---|
| refId | The refId given in the request, if any. |
| error | An error code describing the reason for why the authentication failed. |
The error may be one of the following values:
| Code | Description |
|---|---|
| AUTH_FAILED | A generic code for any kind of failure. |
| CANCELLED | The authentication was cancelled either by the user or the partner. |
| INVALID_ID | The ID has expired or is otherwise invalid. |
| INTERNAL_ERROR | An internal error occurred causing the authentication to fail. |
| SESSION_TIMEOUT | The authentication expired or timed out. |
| UNSUPPORTED_CLIENT | The client used for the authentication is not supported. |
New error codes may be added in the future without prior notice. The partner should therefore handle unknown error codes in their implementations.
Cancel authentication
The DELETE /v3/ftn/auth/{{id}} endpoint is used to cancel an ongoing FTN authentication.
DELETE /v3/ftn/auth/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
IDkollen will respond with HTTP status 204 for successful request, or 4xx/5xx on errors. For more information about errors, please see the Errors section.