## 🇪🇪 Estonia, 🇱🇹 Lithuania, 🇱🇻 Latvia
### Smart-ID & Mobile-ID
Smart-ID and Mobile-ID are secure and user-friendly electronic identification (eID) solutions designed for seamless online authentication. They enable citizens, businesses, and public institutions to access a variety of online services, including banking, e-commerce, government portals, and more.
Smart-ID, predominantly used in the Baltic states (Estonia, Latvia, and Lithuania), is a mobile app that offers a two-step authentication process. It combines a unique user ID, a personal identification number (PIN), and advanced encryption techniques. Users can create a Smart-ID account linked to their national ID or passport, ensuring secure identity verification.
Mobile-ID, on the other hand, is a more generic term for eID solutions that rely on mobile devices and SIM cards with integrated digital certificates, used in Estonia and Lithuania. It requires users to enter a personal identification number (PIN) for authentication, providing a secure method for online identification without additional hardware or software.
Both Smart-ID and Mobile-ID play essential roles in safeguarding users' privacy and security during online transactions, offering secure and seamless authentication experiences across various digital services.
## API Overview
### Core Functionalities
#### Environments
We provide two environments for use:
- **Test** Environment: `https://test-gateway.zignsec.com/core/api/`
- **Production** Environment: `https://gateway.zignsec.com/core/api/`
### REST API
#### Headers
| Header | Description | Required |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Authorization | This header parameter is the subscription key you received from ZignSec during the registration process. Example: `Authorization: 123456add0cff22873c428e987654321` | Yes |
| Content-Type | Specifies the media type of the request body data. Set to `application/json` if the body contains a JSON object. | Yes |
#### API – Documentation
##### Live documentation
- [SmartID API Documentation](https://test-gateway.zignsec.com/api/v3/swagger/index.html#/SmartIdApi)
- [MobileID API Documentation](https://test-gateway.zignsec.com/api/v3/swagger/index.html#/MobileIdApi)
Examples:
- Postman collection
### API Endpoints
#### SmartID
##### Authentication
**Endpoint**: POST /v3.0/eid/smartid/auth - [Swagger UI](https://test-gateway.zignsec.com/api/v3/swagger/index.html#/SmartIdApi/post_api_v_version__eid_smartid_auth)
**Description**: Initiates the authentication process using SmartID. This endpoint is used to start a SmartID authentication session, where the user will verify their identity via SmartID.
##### Signing
**Endpoint**: POST /v3.0/eid/smartid/sign - [Swagger UI](https://test-gateway.zignsec.com/api/v3/swagger/index.html#/SmartIdApi/post_api_v_version__eid_smartid_sign)
**Description**: Initiates a signing process using SmartID. This endpoint allows a user to digitally sign documents or transactions using SmartID, ensuring authenticity and integrity.
##### Get Session Details
**Endpoint**: GET /v3.0/eid/smartid/{sessionId} - [Swagger UI](https://test-gateway.zignsec.com/api/v3/swagger/index.html#/SmartIdApi/get_api_v_version__eid_smartid__sessionId_)
**Description**: Retrieves the status and details of a BankID identity verification session in Norway. It allows you to check the outcome and progress of a previously initiated SmartID verification request.
---
#### MobileID
##### Certificate Request
**Endpoint**: POST /v3.0/eid/mobileid/cert - [Swagger UI](https://test-gateway.zignsec.com/api/v3/swagger/index.html#/MobileIdApi/post_api_v_version__eid_mobileid_cert)
**Description**: Requests a certificate using MobileID. This endpoint is used to obtain a certificate, which can later be used for digital identification or signing actions via MobileID.
##### Authentication
**Endpoint**: POST /v3.0/eid/mobileid/auth - [Swagger UI](https://test-gateway.zignsec.com/api/v3/swagger/index.html#/MobileIdApi/post_api_v_version__eid_mobileid_auth)
**Description**: Initiates the authentication process using MobileID. This endpoint starts the MobileID authentication session, enabling users to verify their identity through their mobile device.
##### Signing
**Endpoint**: POST /v3.0/eid/mobileid/sign - [Swagger UI](https://test-gateway.zignsec.com/api/v3/swagger/index.html#/MobileIdApi/post_api_v_version__eid_mobileid_sign)
**Description**: Initiates a signing process using MobileID. This endpoint is utilized to sign documents or transactions digitally using MobileID, ensuring that the signature is valid and legally binding.
##### Get Session Details
**Endpoint**: GET /v3.0/eid/mobileid/{sessionId} - [Swagger UI](https://test-gateway.zignsec.com/api/v3/swagger/index.html#/MobileIdApi/get_api_v_version__eid_mobileid__sessionId_)
**Description**: Retrieves the status and details of a MobileID identity verification session. This endpoint allows you to check the result of a MobileID verification session that was previously initiated.
### Testing
#### SmartID
To use the test environment there is need to install Smart-ID demo app.
1. **Registration & Installation**
1. Steps to install on Android platform (minimum Android 4.1 required):
[https://play.google.com/apps/testing/com.stagnationlab.sk](https://play.google.com/apps/testing/com.stagnationlab.sk)
2. Steps to install on iOS (minimum iOS12 required):
1. Download Testflight [https://itunes.apple.com/us/app/testflight/id899247664?mt=8](https://itunes.apple.com/us/app/testflight/id899247664?mt=8)
2. Join Smart-ID demo beta app in [https://testflight.apple.com/join/DoWddZjR](https://testflight.apple.com/join/DoWddZjR)
2. **Start the app**
1. Start the Smart-ID app and choose the Register button.
3. **Prove your identity**
1. For beta version, you can choose to prove your identity via provided bank links.
2. Just make your selection and you’ll be redirected to the bank’s Internet bank and you are asked to login with pin calculator, ID-card or Mobile-ID. Using bank link as a registration method means, that you will be granted Smart-ID Basic account. Using ID-card or mobile-ID means, that you will be receiving a Smart-ID Qualified account. Smart-ID Basic can be used only by IDP-s (banks), so we suggest to prefer ID-card or mobile-ID as a registration.
3. After successful login, you’ll arrive back in the app, just confirm that your name and national identification number is correct.
4. If you don’t have supported bank account, you can still try out the app by entering your personal data manually. If you do have Estonian personal ID-code, then you are not eligible for manual registration. Use ‘Other country’ instead if you prefer manual registration. Negative side here is, that you will receive randomly generated personal code, which makes testing more difficult (have to remember that personal code)
4. **Enter your PIN1 and PIN2**
1. The app asks for your PIN1 and PIN2 code. PIN1 is for protecting your authentication key pair and PIN2 is for protecting your signature key pair, same way as with ID-card and Mobile-ID.
2. You can choose the random codes, generated by app, or enter your own favorite PIN code
3. Either way, make sure you remember the codes afterwards.
Your Smart-ID account is now ready to use. If you have iOS watch with watchOS 8.5 or later then you can test Smart-ID from the watch as well.
#### Try it out
To see the Smart-ID in action and to actually use it to log into a website and give the digital signature, you can try the following beta services.
- [https://smid.demo.sk.ee/](https://smid.demo.sk.ee/#login)Â Bank123 demo portal to demonstrate Smart-ID for online banking services
**Disclaimer**
For demo purposes, some of the security features of the Smart-ID demo environment are not identical with the production environment. The Smart-ID demo environment is not intended to be used for security testing.
**Smart-ID test data**
For automated testing you can use this test data: [Test accounts](https://github.com/SK-EID/smart-id-documentation/wiki/Environment-technical-parameters#test-accounts-for-automated-testing)
#### MobileID
To test Mobile ID in the ZignSec test environment, use specific test phone numbers and personal codes to simulate different scenarios like authentication success, invalid signatures, delivery failures, and user cancellations. Test cases cover both Estonian (EE) and Lithuanian (LT) numbers with outcomes such as `SIM_ERROR`, `SIGNATURE_HASH_MISMATCH`, and `USER_CANCELLED`.
For a comprehensive list of test cases and additional information, you can refer to the [Mobile ID Test Numbers Documentation](https://github.com/SK-EID/MID/wiki/Test-number-for-automated-testing-in-DEMO).