Authentication
Start authentication
The POST /freja/auth endpoint is used to start an authentication using Freja eID.
POST /v3/freja/auth
Authorization: Basic ${ base64(accountId + ':' + secretKey) }
{
"ssn": "YYYYMMDDXXXX",
"minRegistrationLevel": "EXTENDED",
"orgNumber": "559000-0948",
"callbackUrl": "https://...",
"refId": "12398698"
}
| Parameter | Required | Description |
|---|---|---|
| ssn | Yes | The Swedish personal identification number of the user to authenticate. |
| minRegistrationLevel | No | Can be one of: 'EXTENDED' or 'PLUS'. The minimum Freja eID registration level that the end user needs to have to be able to authenticate the request. If excluded, the request will default to EXTENDED. |
| refId | No | Reference ID which will be included in a Collect and in the callback. |
| callbackUrl | No | Custom callback URL, must be whitelisted. See Callback. |
| orgNumber | No | Organizational number, 11 digits. Used to perform checks for company signatory. To enable this feature, contact IDkollen. |
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"
}
| 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. |
Fetch result
As an alternative to receiving a callback from IDkollen on successful or failed requests, you can use the
GET /freja/auth/{{id}} endpoint to check the status of an auth request.
NOTE: This endpoint is rate limited to one request per second.
GET /v3/freja/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",
"companySignatoryText": "X är företrädare för Y..."
}
| Parameter | Description |
|---|---|
| refId | The refId given in the request, if any. |
| ssn | A Swedish 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. |
| companySignatoryText | A text describing whether the authenticated user is a signatory for the given organisation number. |
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 /freja/auth/{{id}} endpoint is used to cancel an ongoing Freja authentication.
DELETE /v3/freja/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.