To interact with the ZignSec API, you must authenticate your requests using one of the available authentication methods. This guide outlines the authentication mechanisms supported by ZignSec.
ZignSec offers two primary authentication methods:
- Subscription Key-Based Authentication
- OAuth2 Authentication (Bearer Token)
Additionally, ZignSec supports Two-Way SSL for enhanced security.
For test credentials, contact [**support**](mailto:
[email protected])
### Subscription Key based authentication
With subscription key based authentication, you must provide a subscription key to authenticate your HTTP requests.
These keys are managed by our support team and shared with you securely. There are 2 active keys (Primary and Secondary) and here are some recommendations for managing them:
- Do not publicly expose the keys, share them using secure channels
- Avoid using query parameters to provide your API key
- Do not include the keys in the frontend code
- Do not commit into code repositories
- Rotate keys periodically
- Delete unused keys to minimize exposure to attacks
- Implement retry policy allowing zero-downtime key rotation
- Consider a more secure authorization method
#### Default scheme
The simplest way to authenticate is by using a subscription key. This key must be included in the **Zs-Product-Key** header of your HTTP requests.
```bash
curl https://test-gateway.zignsec.com/core/api/sessions \
-H "Zs-Product-Key: \$subscription_key"
```
This scheme is used for all new (openapi-based) APIs:
- BankID Norway (/api/v5/openapi/bankidno/)
- Scanning (/api/v5/openapi/scanning-dp50/)
- Scanning mobile sdk (/mobilesdk/)
- MitID (/api/v5/openapi/mitid/)
- Watchlist (/api/v5/openapi/watchlist/)
**The header name changed to properly support oauth authentication**
> [!NOTE 1]
> Older products will be migrated to this approach **by the end of 2025**
> [!NOTE 2]
> These products still support the legacy scheme for backward compatibility, but it’s planned to end this support **by Q4 2025**, so it’s highly recommended to start using the new scheme
#### Legacy scheme
For older products **Authorization** header is used
```bash
curl https://test-gateway.zignsec.com/core/api/sessions \
-H "Authorization: $subscription_key"
```
### OAuth2 (oidc) authentication
ZignSec uses OAuth2 for secure authentication. Clients must obtain an access token before making API requests using the token endpoint (the endpoint address to be taken from the proper OpenID configuration)
Introspection endpoint (and <https://jwt.io> site) can be used to view token information
Credentials for authentication are supplied by ZignSec support. Contact [**support**](mailto:
[email protected]) to obtain access credentials.
#### Authentication headers
2 headers are required to authenticate calls – **Authorization** header should contain Bearer jwt token (received from oauth token endpoint), and **Zs-Product-Key** header should contain product id (subscription key) you receive from our support
It's recommended to implement a retry policy and retry if 401 or 403 status code returned with a different key. This way we'll be able to rotate keys zero-downtime.
Please also keep in mind that access token is a short-lived token, its lifetime is 20 minutes by default
---
## 2-Way SSL Certificates
For enhanced security, ZignSec supports Two-Way SSL authentication. This method requires both the client and the server to verify each other using SSL certificates.
- Client Certificate: This is issued by Zignsec support should be sent with every request
- ZignSec Certificate: Ensures mutual authentication.
> [! Security Notice]
>Always store your certificates securely. Notify ZignSec immediately if you suspect any compromise.
**Base URLs for Two-Way SSL Authentication**
- PROD: https://api-prod.zignsec.com
- TEST: https://api-test.zignsec.com
*Example Request*
``` bash
curl -X POST "https://api-test.zignsec.com/core/api/sessions/bankidse/auth" \
-H "Content-Type: application/json" \
-H "Zs-Product-Key: $subscription_key" \
--cert $client_cert_file \
--key $client_cert_file \
-d '{
"personalNumber": "198001011234",
"endUserIp": "192.168.1.1"
}'
```