Authentication
Start IVR auth
The POST /v3/ivr endpoint is used to start an IVR auth.
POST /v3/ivr
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
{
"providers": ["BANKID_SE", "VIPPS"],
"language": "ENGLISH",
"email": "E-mail",
"phone": "Phone number",
"callbackUrl": "https://...",
"refId": "12398698"
}
| Parameter | Required | Description |
|---|---|---|
| providers | Yes | The eID providers that should be available to the end user. Must be at least one and can either 'BANKID_SE', 'BANKID_NO', 'MITID', or 'FTN' |
| language | No | The default user of the user interface. Can be one of 'ENGLISH', 'SWEDISH', 'NORWEGIAN', 'DANISH', 'FINNISH' |
| No | An e-mail address to send a notification to | |
| phone | No | A phone number to send a notification to |
| callbackUrl | No | A URL where IDkollen will send a callback on successful or failed requests. |
| refId | No | Reference ID which will be included in a Collect and in the callback. |
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 IVR auth request. |
| refId | The refId given in the request, if any. |
| url | The URL where the end user can authenticate themselves. |
Fetch result
The GET /v3/ivr/{{id}} endpoint is used to check the status of an IVR auth request.
NOTE: This endpoint is rate limited to one request per second.
GET /v3/ivr/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
This endpoint will respond with a HTTP status of 404 if the IVR auth session has expired.
The status of an IVR auth can be either one of: PENDING, COMPLETED or FAILED.
Pending
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "PENDING",
"url": "https://..."
}
| Parameter | Description |
|---|---|
| refId | The refId given in the request, if any. |
| url | The URL where the end user can authenticate themselves. |
Completed
{
"id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
"refId": "12398698",
"status": "COMPLETED"
}
| Parameter | Description |
|---|---|
| refId | The refId given in the request, if any. |
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 IVR auth failed. |
The error may be one of the following values:
| Code | Description |
|---|---|
| AUTH_FAILED | A generic code for any kind of failure. |
| CANCELLED | The IVR auth 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 IVR auth to fail. |
| SESSION_TIMEOUT | The IVR auth expired or timed out. |
| UNSUPPORTED_CLIENT | The client used for the IVR auth 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 IVR auth
The DELETE /v3/ivr/{{id}} endpoint is used to cancel an ongoing BankID (SE) IVR auth.
DELETE /v3/ivr/{{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.