API Reference

Base Client

class bankid.baseclient.BankIDClientBaseclass(certificates: Tuple[str, str], test_server: bool = False, request_timeout: int = 5)[source]

Baseclass for BankID clients.

Both the synchronous and asynchronous clients inherit from this base class and has the methods implemented here.

Synchronous Client

class bankid.syncclient.BankIDClient(certificates: Tuple[str, str], test_server: bool = False, request_timeout: int = 5)[source]

The synchronous client to use for communicating with BankID servers via the v6 API.

Parameters:

certificates (tuple) – Tuple of string paths to the certificate to use and the key to sign with.
test_server (bool) – Use the test server for authenticating and signing.
request_timeout (int) – Timeout for BankID requests.

authenticate(end_user_ip: str, requirement: Dict[str, Any] | None = None, user_visible_data: str | None = None, user_non_visible_data: str | None = None, user_visible_data_format: str | None = None) → Dict[str, str][source]

Request an authentication order. The collect() method is used to query the status of the order.

Example data returned:

{
    "orderRef": "ee3421ea-2096-4000-8130-82648efe0927",
    "autoStartToken": "e8df5c3c-c67b-4a01-bfe5-fefeab760beb",
    "qrStartToken": "01f94e28-857f-4d8a-bf8e-6c5a24466658",
    "qrStartSecret": "b4214886-3b5b-46ab-bc08-6862fddc0e06"
}

Parameters:

end_user_ip (str) – The user IP address as seen by RP. String. IPv4 and IPv6 is allowed.
requirement (dict) – Requirements on how the auth order must be performed. See the section Requirements for more details.
user_visible_data (str) – Text displayed to the user during authentication with BankID, with the purpose of providing context for the authentication and to enable users to detect identification errors and averting fraud attempts.
user_non_visible_data (str) – Data is not displayed to the user.
user_visible_data_format (str) – If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters which potentially make for a more pleasant user experience.

Returns:

The order response.

Return type:

dict

Raises:

BankIDError – raises a subclass of this error when error has been returned from server.

cancel(order_ref: str) → bool[source]

Cancels an ongoing sign or auth order.

This is typically used if the user cancels the order in your service or app.

Parameters:: order_ref (str) – The UUID string specifying which order to cancel.
Returns:: Boolean regarding success of cancellation.
Return type:: bool
Raises:: BankIDError – raises a subclass of this error when error has been returned from server.

collect(order_ref: str) → dict[source]

Collects the result of a sign or auth order using the orderRef as reference.

RP should keep on calling collect every two seconds if status is pending. RP must abort if status indicates failed. The user identity is returned when complete.

Example collect results returned while authentication or signing is still pending:

{
    "orderRef":"131daac9-16c6-4618-beb0-365768f37288",
    "status":"pending",
    "hintCode":"userSign"
}

Example collect result when authentication or signing has failed:

{
    "orderRef":"131daac9-16c6-4618-beb0-365768f37288",
    "status":"failed",
    "hintCode":"userCancel"
}

Example collect result when authentication or signing is successful and completed:

{
    "orderRef": "131daac9-16c6-4618-beb0-365768f37288",
    "status": "complete",
    "completionData": {
        "user": {
            "personalNumber": "190000000000",
            "name": "Karl Karlsson",
            "givenName": "Karl",
            "surname": "Karlsson"
        },
        "device": {
            "ipAddress": "192.168.0.1"
        },
        "bankIdIssueDate": "2020-02-01",
        "signature": "<base64-encoded data>",
        "ocspResponse": "<base64-encoded data>"
    }
}

See BankID Integration Guide for more details about how to inform end user of the current status, whether it is pending, failed or completed.

Parameters:: order_ref (str) – The orderRef UUID returned from auth or sign.
Returns:: The CollectResponse parsed to a dictionary.
Return type:: dict
Raises:: BankIDError – raises a subclass of this error when error has been returned from server.

phone_authenticate(personal_number: str, call_initiator: str, requirement: Dict[str, Any] | None = None, user_visible_data: str | None = None, user_non_visible_data: str | None = None, user_visible_data_format: str | None = None) → Dict[str, str][source]

Initiates an authentication order when the user is talking to the RP over the phone. The collect() method is used to query the status of the order.

Example data returned:

{
    "orderRef": "ee3421ea-2096-4000-8130-82648efe0927"
}

Parameters:

personal_number (str) – The personal number of the user. 12 digits.
call_initiator (str) – Indicate if the user or the RP initiated the phone call. “user”: user called the RP “RP”: RP called the user
requirement (dict) –
Requirements on how the auth order must be performed. See the section Requirements for more details.
user_visible_data (str) – Text displayed to the user during authentication with BankID, with the purpose of providing context for the authentication and to enable users to detect identification errors and averting fraud attempts.
user_non_visible_data (str) – Data is not displayed to the user.
user_visible_data_format (str) – If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters which potentially make for a more pleasant user experience.

Returns:

The order response.

Return type:

dict

Raises:

BankIDError – raises a subclass of this error when error has been returned from server.

phone_sign(personal_number: str, call_initiator: str, user_visible_data: str, requirement: Dict[str, Any] | None = None, user_non_visible_data: str | None = None, user_visible_data_format: str | None = None) → Dict[str, str][source]

Initiates an authentication order when the user is talking to the RP over the phone. The collect() method is used to query the status of the order.

Example data returned:

{
    "orderRef": "ee3421ea-2096-4000-8130-82648efe0927"
}

Parameters:

personal_number (str) – The personal number of the user. 12 digits.
call_initiator (str) – Indicate if the user or the RP initiated the phone call. “user”: user called the RP “RP”: RP called the user
requirement (dict) –
Requirements on how the sign order must be performed. See the section Requirements for more details.
user_visible_data (str) – Text to be displayed to the user.
user_non_visible_data (str) – Data is not displayed to the user.
user_visible_data_format (str) – If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters which potentially make for a more pleasant user experience.

Returns:

The order response.

Return type:

dict

Raises:

BankIDError – raises a subclass of this error when error has been returned from server.

sign(end_user_ip: str, user_visible_data: str, requirement: Dict[str, Any] | None = None, user_non_visible_data: str | None = None, user_visible_data_format: str | None = None) → Dict[str, str][source]

Request a signing order. The collect() method is used to query the status of the order.

Example data returned:

{
    "orderRef": "ee3421ea-2096-4000-8130-82648efe0927",
    "autoStartToken": "e8df5c3c-c67b-4a01-bfe5-fefeab760beb",
    "qrStartToken": "01f94e28-857f-4d8a-bf8e-6c5a24466658",
    "qrStartSecret": "b4214886-3b5b-46ab-bc08-6862fddc0e06"
}

Parameters:

end_user_ip (str) – The user IP address as seen by RP. String. IPv4 and IPv6 is allowed.
requirement (dict) –
Requirements on how the sign order must be performed. See the section Requirements for more details.
user_visible_data (str) – Text to be displayed to the user.
user_non_visible_data (str) – Data is not displayed to the user.
user_visible_data_format (str) – If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters which potentially make for a more pleasant user experience.

Returns:

The order response.

Return type:

dict

Raises:

BankIDError – raises a subclass of this error when error has been returned from server.

Asynchronous Client

class bankid.asyncclient.BankIDAsyncClient(certificates: Tuple[str, str], test_server: bool = False, request_timeout: int = 5)[source]

The asynchronous client to use for communicating with BankID servers via the v6 API.

Parameters:

certificates (tuple) – Tuple of string paths to the certificate to use and the key to sign with.
test_server (bool) – Use the test server for authenticating and signing.
request_timeout (int) – Timeout for BankID requests.

async authenticate(end_user_ip: str, requirement: Dict[str, Any] | None = None, user_visible_data: str | None = None, user_non_visible_data: str | None = None, user_visible_data_format: str | None = None) → Dict[str, str][source]

Request an authentication order. The collect() method is used to query the status of the order.

Example data returned:

{
    "orderRef": "ee3421ea-2096-4000-8130-82648efe0927",
    "autoStartToken": "e8df5c3c-c67b-4a01-bfe5-fefeab760beb",
    "qrStartToken": "01f94e28-857f-4d8a-bf8e-6c5a24466658",
    "qrStartSecret": "b4214886-3b5b-46ab-bc08-6862fddc0e06"
}

Parameters:

end_user_ip (str) – The user IP address as seen by RP. String. IPv4 and IPv6 is allowed.
requirement (dict) –
Requirements on how the auth order must be performed. See the section Requirements for more details.
user_visible_data (str) – Text displayed to the user during authentication with BankID, with the purpose of providing context for the authentication and to enable users to detect identification errors and averting fraud attempts.
user_non_visible_data (str) – Data is not displayed to the user.
user_visible_data_format (str) – If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters which potentially make for a more pleasant user experience.

Returns:

The order response.

Return type:

dict

Raises:

BankIDError – raises a subclass of this error when error has been returned from server.

async cancel(order_ref: str) → bool[source]

Cancels an ongoing sign or auth order.

This is typically used if the user cancels the order in your service or app.

Parameters:: order_ref (str) – The UUID string specifying which order to cancel.
Returns:: Boolean regarding success of cancellation.
Return type:: bool
Raises:: BankIDError – raises a subclass of this error when error has been returned from server.

async collect(order_ref: str) → dict[source]

Collects the result of a sign or auth order using the orderRef as reference.

RP should keep on calling collect every two seconds if status is pending. RP must abort if status indicates failed. The user identity is returned when complete.

Example collect results returned while authentication or signing is still pending:

{
    "orderRef":"131daac9-16c6-4618-beb0-365768f37288",
    "status":"pending",
    "hintCode":"userSign"
}

Example collect result when authentication or signing has failed:

{
    "orderRef":"131daac9-16c6-4618-beb0-365768f37288",
    "status":"failed",
    "hintCode":"userCancel"
}

Example collect result when authentication or signing is successful and completed:

{
    "orderRef": "131daac9-16c6-4618-beb0-365768f37288",
    "status": "complete",
    "completionData": {
        "user": {
            "personalNumber": "190000000000",
            "name": "Karl Karlsson",
            "givenName": "Karl",
            "surname": "Karlsson"
        },
        "device": {
            "ipAddress": "192.168.0.1"
        },
        "bankIdIssueDate": "2020-02-01",
        "signature": "<base64-encoded data>",
        "ocspResponse": "<base64-encoded data>"
    }
}

See BankID Integration Guide for more details about how to inform end user of the current status, whether it is pending, failed or completed.

Parameters:: order_ref (str) – The orderRef UUID returned from auth or sign.
Returns:: The CollectResponse parsed to a dictionary.
Return type:: dict
Raises:: BankIDError – raises a subclass of this error when error has been returned from server.

async phone_authenticate(personal_number: str, call_initiator: str, requirement: Dict[str, Any] | None = None, user_visible_data: str | None = None, user_non_visible_data: str | None = None, user_visible_data_format: str | None = None) → Dict[str, str][source]

Initiates an authentication order when the user is talking to the RP over the phone. The collect() method is used to query the status of the order.

Example data returned:

{
    "orderRef": "ee3421ea-2096-4000-8130-82648efe0927"
}

Parameters:

personal_number (str) – The personal number of the user. 12 digits.
call_initiator (str) – Indicate if the user or the RP initiated the phone call. “user”: user called the RP “RP”: RP called the user
requirement (dict) –
Requirements on how the auth order must be performed. See the section Requirements for more details.
user_visible_data (str) – Text displayed to the user during authentication with BankID, with the purpose of providing context for the authentication and to enable users to detect identification errors and averting fraud attempts.
user_non_visible_data (str) – Data is not displayed to the user.
user_visible_data_format (str) – If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters which potentially make for a more pleasant user experience.

Returns:

The order response.

Return type:

dict

Raises:

BankIDError – raises a subclass of this error when error has been returned from server.

async phone_sign(personal_number: str, call_initiator: str, user_visible_data: str, requirement: Dict[str, Any] | None = None, user_non_visible_data: str | None = None, user_visible_data_format: str | None = None) → Dict[str, str][source]

Initiates an authentication order when the user is talking to the RP over the phone. The collect() method is used to query the status of the order.

Example data returned:

{
    "orderRef": "ee3421ea-2096-4000-8130-82648efe0927"
}

Parameters:

personal_number (str) – The personal number of the user. 12 digits.
call_initiator (str) – Indicate if the user or the RP initiated the phone call. “user”: user called the RP “RP”: RP called the user
requirement (dict) –
Requirements on how the sign order must be performed. See the section Requirements for more details.
user_visible_data (str) – Text to be displayed to the user.
user_non_visible_data (str) – Data is not displayed to the user.
user_visible_data_format (str) – If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters which potentially make for a more pleasant user experience.

Returns:

The order response.

Return type:

dict

Raises:

BankIDError – raises a subclass of this error when error has been returned from server.

async sign(end_user_ip: str, user_visible_data: str, requirement: Dict[str, Any] | None = None, user_non_visible_data: str | None = None, user_visible_data_format: str | None = None) → Dict[str, str][source]

Request a signing order. The collect() method is used to query the status of the order.

Example data returned:

{
    "orderRef": "ee3421ea-2096-4000-8130-82648efe0927",
    "autoStartToken": "e8df5c3c-c67b-4a01-bfe5-fefeab760beb",
    "qrStartToken": "01f94e28-857f-4d8a-bf8e-6c5a24466658",
    "qrStartSecret": "b4214886-3b5b-46ab-bc08-6862fddc0e06"
}

Parameters:

end_user_ip (str) – The user IP address as seen by RP. String. IPv4 and IPv6 is allowed.
requirement (dict) –
Requirements on how the sign order must be performed. See the section Requirements for more details.
user_visible_data (str) – Text to be displayed to the user.
user_non_visible_data (str) – Data is not displayed to the user.
user_visible_data_format (str) – If present, and set to “simpleMarkdownV1”, this parameter indicates that userVisibleData holds formatting characters which potentially make for a more pleasant user experience.

Returns:

The order response.

Return type:

dict

Raises:

BankIDError – raises a subclass of this error when error has been returned from server.

QR Utils

bankid.qr.generate_qr_code_content(qr_start_token: str, start_t: float | datetime, qr_start_secret: str) → str[source]: Given QR start token, time.time() or UTC datetime when initiated authentication call was made and the QR start secret, calculate the current QR code content to display.

Exceptions

exception bankid.exceptions.AlreadyInProgressError(*args: Any, **kwargs: Any)[source]

Failure to create new order due to one already in progress.

Code: alreadyInProgress

Reason: An order for this user is already in progress. The order is aborted. No order is created.

Action by RP: RP must inform the user that a login or signing operation is already initiated for this user. Message RFA4 should be used.

exception bankid.exceptions.BankIDError(*args: Any, raw_data: Dict[str, Any] | None = None, **kwargs: Any)[source]: Parent exception class for all PyBankID errors.

exception bankid.exceptions.BankIDWarning[source]: Warning class for PyBankID.

exception bankid.exceptions.InternalError(*args: Any, **kwargs: Any)[source]

Remote server error.

Code: internalError

Reason: Internal technical error in the BankID system.

Action by RP: RP must not automatically try again. RP must inform the user that a technical error has occurred. Message RFA5 should be used.

exception bankid.exceptions.InvalidParametersError(*args: Any, **kwargs: Any)[source]

User induced error.

Code: invalidParameters

Reason: Invalid parameter. Invalid use of method.

Action by RP: RP must not try the same request again. This is an internal error within RP’s system and must not be ‘ communicated to the user as a BankID error.

exception bankid.exceptions.MaintenanceError(*args: Any, **kwargs: Any)[source]

The service is temporarily out of service.

Code: maintenance

Action by RP: RP may try again without informing the user. If this error is returned repeatedly, RP must inform the user. Message RFA5.

exception bankid.exceptions.NotFoundError(*args: Any, **kwargs: Any)[source]

An erroneous URL path was used.

Code: notFound

Action by RP: RP must not try the same request again. This is an internal error within RP’s system and must not be ‘ communicated to the user as a BankID error.

exception bankid.exceptions.RequestTimeoutError(*args: Any, **kwargs: Any)[source]

It took too long time to transmit the request.

Code: requestTimeout

Action by RP: RP must not automatically try again. This error may occur if the processing at RP or the communication is too slow. RP must inform the user. Message RFA5

exception bankid.exceptions.UnauthorizedError(*args: Any, **kwargs: Any)[source]

RP does not have access to the service.

Code: unauthorized

Action by RP: RP must not try the same request again. This is an internal error within RP’s system and must not be ‘ communicated to the user as a BankID error.