Authorization and Authentication

Without authentication and authorization you'll only get access to roughly half of our API calls and features. for example in order to buy contracts or utilize the Copy Trading features your users must be authenticated and authorized by our OAuth provider and Websocket Server.

Before we start

You have to make sure you have all the requirements mentioned bellow to continue.

Requirements

1. Deriv Account
2. Deriv API Token with the appropriate access level
3. Deriv App ID

remarque

Please refer to Setting up a Deriv Application for detailed instruction how to create Deriv API token and Applications

API Token

An API token is a unique identifier of a client that requests access from a server. It's the simplest way of authorization.

The access level for each API token has to match the required access level of each API call, which can be found in the API Explorer as well.

For example, on the screenshot below, you can see that to be able to use the Account Status, a token with read access level must be used.

Following the authorization of a Websocket connection, subsequent calls on that connection will be considered user actions.

Please bear in mind that the API token can be used with any app, so both your app and your clients need to keep it secure.

OAuth2

OAuth stands for Open Authorization - a protocol that allows a client access resources hosted on a server on behalf of the user without revealing the credentials.

This type of authorization allows clients to log in to third-party apps using their Deriv accounts without creating an API token. In this case, the third-party app does not see the user's password or permanent API token, which makes it safer.

The OAuth2 authentication requires more steps to set up, but it is the safest way for developers to share access to their app with their clients.

For more information on OAuth2, visit this guide.

Here is the visual representation of how the OAuth authorization connection works:

Authentication Process

In order to Authenticate your user, specify the URL that will be used as the OAuth Redirect URL on the Dashboard page, Register application tab in the OAuth details fields and then Add a login button on your website or app and direct users to https://oauth.binary.com/oauth2/authorize?app_id=your_app_id where your_app_id is the ID of your app.

Once a user signs up / signs in, they will be redirected to the URL that you entered as the Redirect URL. This URL will have arguments added to it with the user's session tokens, and will look similar to this:

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

Authorization Process

The query params in the redirect URL are the user's accounts and their related session tokens. you can map the query params to an array like so:

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

To authorize the user, based on the user's Selected account, call the authorize API call with the user's Selected account Session Token:

{
  "authorize": "a1-f7pnteezo4jzhpxclctizt27hyeot"
}

The response for the authorize call would be an object like so:

{
    "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 user is authorized and you use Deriv API calls on behalf of the account.