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're a Deriv partner and want to ensure that all your users are correctly tagged under your account, you must include your affiliate token and UTM campaign in the OAuth URL for sign in.
   For example: https://oauth.deriv.com/oauth2/authorize?app_id=YOUR_APP_ID&affiliate_token=YOUR_TOKEN&utm_campaign=YOUR_CAMPAIGN
   
   
   You’ll find these values in the referral links shared with you. Here’s how to extract and use them:
   1. If your referral link looks like:
      https://deriv.com/signup?sidc=FB58247C-6B33-4677-A6AD-168C2D72323C&utm_campaign=dynamicworks&utm_medium=affiliate&utm_source=CU00001
      Your affiliate_token is the sidc value: FB58247C-6B33-4677-A6AD-168C2D72323C
      Your utm_campaign is: dynamicworks
      Your OAuth URL should be:
      https://oauth.deriv.com/oauth2/authorize?app_id=YOUR_APP_ID&affiliate_token=FB58247C-6B33-4677-A6AD-168C2D72323C&utm_campaign=dynamicworks
   2. If your referral link looks like:
      https://track.deriv.com/_jqd7qq_iBB18zg8lBvFoLmNd7ZgqdRLk/1/
      Your affiliate_token is: jqd7qq_iBB18zg8lBvFoLmNd7ZgqdRLk
      Your utm_campaign is: myaffiliates
      Your OAuth URL should be:
      https://oauth.deriv.com/oauth2/authorize?app_id=YOUR_APP_ID&affiliate_token=jqd7qq_iBB18zg8lBvFoLmNd7ZgqdRLk&utm_campaign=myaffiliates
      Adding these parameters ensures proper referral tracking and commissions under your partnership.

📘

Important note:

For sign-ups, use the parameter t and utm_campaign:

JSON

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

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.