Authentication

To unlock the complete functionality of Deriv APIs, you must first authenticate and then authorize your users.

For Deriv APIs, your users must be authenticated and authorized by our OAuth provider and WebSocket Server.

The OAuth provider handles user logins and grants secure access tokens. The WebSocket server then uses these tokens to verify users and facilitate seamless communication with the Deriv API. Together, these components ensure the security and efficiency of your app.

Authentication process

OAuth, short for Open Authorization, is a protocol that enables a client to access server-hosted resources on behalf of the user without exposing their credentials. For more information, refer to OAuth.

This method enables Deriv account holders to log into third-party apps without generating an API token. Consequently, the third-party app does not access the user’s password or permanent API token, enhancing security.

To authenticate your user:

1. Make sure the URL is specified correctly in the OAuth Details. To verify this, navigate to the Application manager under the Applications tab in the Dashboard and click the copy icon to copy the OAuth redirect URL. To change or update the URL, click the pencil icon next to the app you want to edit.
2. Add a login button on your website or app.
3. When users click the button, automatically send them to the following URL: https://oauth.deriv.com/oauth2/authorize?app_id=YOUR_APP_ID
   Replace YOUR_APP_ID with the actual ID of your app (found under Dashboard → Applications → Application manager).
4. If you have an affiliate token for sign in, include it by appending &affiliate_token=YOUR_TOKEN.
   For example: https://oauth.deriv.com/oauth2/authorize?app_id=YOUR_APP_ID&affiliate_token=YOUR_TOKEN

📘

Important note:

For sign-ups, use the parameter t:

JSON

https://hub.deriv.com/tradershub/signup?t=YOUR_TOKEN

When the user completes the signup or login, they will be redirected to the Redirect URL.

The redirected URL will include appended arguments containing the user's session tokens. For instance:

https://[YOUR_WEBSITE_URL]/redirect/?acct1=cr799393& token1=a1-f7pnteezo4jzhpxclctizt27hyeot&cur1=usd& acct2=vrtc1859315& token2=a1clwe3vfuuus5kraceykdsoqm4snfq& cur2=usd

Authorisation process

The query parameters within the redirect URL represent the user's accounts and associated session tokens.

1. To convert these query parameters into an array, follow this approach:

   JSON

   const user_accounts = [
     {
       account: 'cr799393',
       token: 'a1-f7pnteezo4jzhpxclctizt27hyeot',
       currency: 'usd',
     },
     {
       account: 'vrtc1859315',
       token: 'a1clwe3vfuuus5kraceykdsoqm4snfq',
       currency: 'usd',
     },
   ];
   

2. Call the authorize API using the session token linked to the selected user's account to grant authorization.

   JSON

   {
     "authorize": "a1-f7pnteezo4jzhpxclctizt27hyeot"
   }
   
   

   The response to the authorize call is an object as follows:

   JSON

   {
       "account_list": [
         {
           "account_type": "trading",
           "created_at": 1647509550,
           "currency": "USD",
           "is_disabled": 0,
           "is_virtual": 0,
           "landing_company_name": "svg",
           "loginid": "CR799393",
           "trading": {}
         },
         {
           "account_type": "trading",
           "created_at": 1664132232,
           "currency": "ETH",
           "is_disabled": 0,
           "is_virtual": 0,
           "landing_company_name": "svg",
           "loginid": "VRTC1859315",
           "trading": {}
         },
       ],
       "balance": 0,
       "country": "id",
       "currency": "USD",
       "email": "user_mail@email_provider.com",
       "fullname": " John Doe",
       "is_virtual": 0,
       "landing_company_fullname": "Deriv (SVG) LLC",
       "landing_company_name": "svg",
       "local_currencies": {
         "IDR": {
           "fractional_digits": 2
         }
       },
       "loginid": "CR799393",
       "preferred_language": "EN",
       "scopes": [
         "read",
         "trade",
         "trading_information",
         "payments",
         "admin"
       ],
       "trading": {},
        "upgradeable_landing_companies": [
         "svg"
       ],
       "user_id": 12345678
     }
   

Now that the selected user is authorised, and you can use Deriv API calls on behalf of the account.