Cboe LiveVol APIs use the OAuth 2.0 and OpenID Connect 1.0 protocols for authentication and authorization. We support authentication using the Authorization Code Flow and the Client Credentials Flow. Other flows can be supported based on client need.
Learn more about OpenID Connect 1.0 / OAuth 2.0 »
Client Credentials Flow
This is used for machine to machine communication.
1. Request Authorization
The request is sent to the Token endpoint.
| Method | POST | ||
|---|---|---|---|
| Endpoint | connect/token | ||
| Request Body Parameters | name | required | description |
| grant_type | Set it to “client_credentials”. | ||
| Request Headers | name | required | description |
| Authorization | Base 64 encoded string that contains the client ID and client secret key. The field must have the format: Basic <base64 encoded client_id:client_secret>. | ||
| Request example |
POST https://id.livevol.com/connect/token HTTP/1.1 Authorization: Basic ZXhhbXBsZUNsaWVudDpleGFtcGxlQ2xpZW50U2VjcmV0 grant_type=client_credentials |
||
| Response example |
HTTP/1.1 200 OK Content-Type: application/json {"access_token":"eyJ0eXAiOi...","expires_in":3600,"token_type":"Bearer"} |
||
2. Use the Access Token
Once you have obtained an access token it must be provided in Authorization HTTP header in each WebAPI request.
| Request example |
GET https://api.livevol.com/v1/market/symbols HTTP/1.1 Authorization: Bearer 70dd2395eae0d98c85b58804dd429f48 |
||
|---|---|---|---|
Authorization Code Flow
This flow should be used for browser-based applications. It can also be used by native applications than can interact with the system browser or applications that have a built in browser like WPF. In this method you will register your application with Cboe LiveVol, redirect a browser to a URL, parse the token from the responding redirect, and then send the token to the appropriate API.
1. Request Authorization
The authorization process starts with your application sending a request to the Authorize endpoint to receive an authorization code.
The request will include parameters in the query string.
| Method | GET | ||
|---|---|---|---|
| Endpoint | connect/authorize | ||
| Parameters | name | required | description |
| client_id | Your application consumer key. | ||
| redirect_uri | The URI to redirect to after the user grants/denies permission. This URI needs to have been entered in the Redirect URI whitelist that you specified when you registered your application. The value of redirect_uri here must exactly match one of the values you entered when you registered your application. | ||
| response_type | Set it to “code”. | ||
| state | Any unique string generated by your application. | ||
| Request | https://id.livevol.com/connect/authorize?client_id=exampleClient&redirect_uri=http://example.com/home.html&response_type=code&state=1234 | ||
2. User login
The client will be redirected to the Cboe LiveVol IdentityServer and asked to login and grant access.
3. Redirect
After the user accepts (or denies) your request, the Cboe LiveVol IdentityServer redirects back to the redirect_uri.
If the user has accepted your request, the response query string contains the following parameters.
| Parameters | name | description |
|---|---|---|
| code | Your application consumer key. | |
| state | The value of the state parameter supplied in the request. | |
| Response example | HTTP/1.1 302 Found Location: http://example.com/home.html?code=b6ae661ae563d2dbd7f81607bbc3cecd&state=1234 | |
Note: The reason state is sent back in the redirect is to make sure there was no tampering. You should make sure state is the same value you sent in step 1.
4. Request Access Token
When the authorization code has been received, you will need to exchange it for an access token by making a POST request to the Cboe LiveVol IdentityServer, this time to its Token endpoint.
| Method | POST | ||
|---|---|---|---|
| Endpoint | connect/token | ||
| Request Body Parameters | name | required | description |
| grant_type | This field must contain the value "authorization_code". | ||
| code | The authorization code received in the previous callback. | ||
| Request Headers | name | required | description |
| Authorization | Base 64 encoded string that contains the client ID and client secret key. The field must have the format: Basic <base64 encoded client_id:client_secret>. | ||
| Content-type | application/x-www-form-urlencoded. | ||
| Request example |
POST https://id.livevol.com/connect/token HTTP/1.1 Authorization: Basic ZXhhbXBsZUNsaWVudDpleGFtcGxlQ2xpZW50U2VjcmV0 Content-type: application/x-www-form-urlencoded grant_type=authorization_code&code=fe3d78c2a4175096cc981a703845387c&redirect_uri=example.com/home.html |
||
| Response example |
HTTP/1.1 200 OK Content-Type: application/json {"access_token":"eyJ0eXAiOi...","expires_in":3600,"token_type":"Bearer"} |
||
5. Use the Access Token
Once you have obtained an access token it must be provided in Authorization HTTP header in each WebAPI request.
| Request example |
GET https://api.livevol.com/v1/market/symbols HTTP/1.1 Authorization: Bearer 70dd2395eae0d98c85b58804dd429f48 |
||
|---|---|---|---|
6. Refresh Access Token
Since access tokens have finite lifetimes, refresh tokens allow requesting new access tokens without user interaction.
To obtain a refresh token parse the 'refresh_token' field from response of Access Token request
| Authorization Request example | GET https://id.livevol.com/connect/authorize?client_id=exampleClient&redirect_uri=http://example.com/home.html&response_type=code&state=1234 HTTP/1.1 | ||
|---|---|---|---|
| Access Token Response example |
HTTP/1.1 200 OK Content-Type: application/json {"access_token":"eyJ0eXAiOi...","expires_in":3600,"token_type":"Bearer","refresh_token":"be4746f..."} |
||
To obtain a new access token using refresh token send the request to the Token endpoint and parse the new values of access token and refresh token from response.
| Method | POST | ||
|---|---|---|---|
| Endpoint | connect/token | ||
| Request Body Parameters | name | required | description |
| grant_type | This field must contain the value "refresh_token". | ||
| refresh_token | The value of obtained Refresh token. | ||
| Request Headers | name | required | description |
| Authorization | Base 64 encoded string that contains the client ID and client secret key. The field must have the format: Basic <base64 encoded client_id:client_secret>. | ||
| Content-type | application/x-www-form-urlencoded. | ||
| Request example |
POST https://id.livevol.com/connect/token HTTP/1.1 Authorization: Basic ZXhhbXBsZUNsaWVudDpleGFtcGxlQ2xpZW50U2VjcmV0 Content-type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=be4746f7b19f27f702cf7c80e9b0bda4 |
||
| Response example |
HTTP/1.1 200 OK Content-Type: application/json {"access_token":"9dd391...","expires_in":3600,"token_type":"Bearer","refresh_token":"f26d6a..."} |
||