Authentication - Securing Your API Requests

Unblock API employs a dual authentication method to ensure secure and authorized access to our services. This approach allows us to:

• Identify your Merchant Account: Using API Keys, we verify that requests originate from a registered and authorized partner.
• Authorize User Actions: Session IDs ensure that any actions modifying user data are explicitly consented to by the individual user.

Understanding both API Keys and Session IDs is crucial for successful integration.

🔑 API Keys: Merchant-Level Authentication

API Keys are your primary credential for authenticating your Merchant account with the Unblock API.

• Purpose: API Keys identify your business as a registered Unblock partner, allowing access to Merchant-level endpoints and general data retrieval.

• Usage: Include your API Key in the Authorization header of every API request.

  Authorization: API-Key YOUR_API_KEY
  

  Example using curl:

  Bash

  curl --request GET \
       --url 'https://sandbox.getunblock.com/exchange-rates/?base_currency=EUR&target_currency=USD' \
       --header 'Authorization: API-Key YOUR_API_KEY' \
       --header 'accept: application/json'
  

• Environment-Specific: API Keys are linked to specific Environments (Sandbox, Production). Ensure you are using the correct API Key for the environment you are working in.

• Backend Usage: API Keys are designed for server-side (backend) use only. Never expose API Keys in client-side code (front-end applications), public repositories, or insecure channels. This is critical for protecting your integration and user data.

• Security is Paramount: If an API Key is compromised or publicly exposed, Unblock will deactivate it immediately without notice to prevent unauthorized access and potential data breaches.

👤 Session IDs: User-Level Authorization

Session IDs are required for endpoints that create, modify, or access data related to individual users (Individuals or Corporates).

• Purpose: Session IDs ensure that user-specific actions are authorized and consented to by the user. This is vital for data privacy and regulatory compliance.

• Usage: Include the Session ID in the unblock-session-id header for relevant API requests (typically POST, PUT, PATCH requests for user-related endpoints).

  unblock-session-id: YOUR_SESSION_ID
  

  Example using curl:

  Bash

  curl --request POST \
       --url https://sandbox.getunblock.com/user/bank-account/unblock \
       --header 'Authorization: API-Key YOUR_API_KEY' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --header 'unblock-session-id: YOUR_SESSION_ID' \
       --data '{"currency":"EUR"}'
  

• Obtaining Session IDs: You can obtain a Session ID through two methods:

  1. Email One-Time Password (OTP): Initiate an OTP login flow to send an OTP to the user's email and then exchange the OTP for a Session ID. Learn about OTP Login.
  2. Sign-In with Ethereum (SIWE): Use the SIWE standard to allow users to authenticate using their crypto wallet and obtain a Session ID. Learn about SIWE Login

• Validity and Renewal: Session IDs are valid for 4 hours. After expiration, a new Session ID must be generated through the login process. Only one Session ID can be active at a time per user.

• GET Endpoints (Data Retrieval): GET endpoints that retrieve user data generally do not require a Session ID. User identification for data retrieval is typically handled through the user_uuid parameter (when required) and Merchant API Key authorization.

When to Use API Keys vs. Session IDs: Quick Guide

By correctly implementing both API Key and Session ID authentication, you ensure the security and compliance of your Unblock API integration, providing a safe and reliable experience for your users.