Demyst supports OAuth 2.0 protocol for authorisation. You could obtain access to our Data API services, as a resource owner by orchestrating an approval interaction between the resource owner and our services.

📘

Grant type supported

Demyst supports resource owner credentials OAuth 2.0 grant (RFC 6749, §4.3) and a refresh token OAuth 2.0 grant (RFC 6749, §1.5, §5). These grant types provide different options for authentication and authorisation in the OAuth 2.0 framework, offering flexibility in different application scenarios.

Resource Owner Credentials Grant (RFC 6749, §4.3)

• This grant type allows Clients to obtain an access token by presenting the resource owner's (end user's) credentials, i.e. username and password, directly to our authorisation server.
• The Client application collects the user's credentials and includes them in the token request to our authorisation server.
• Client ID and Client Secret are typically used for Client authentication, while the username and password are used for resource owner authentication (also known as the "password grant type").

Refresh Token Grant (RFC 6749, §1.5, §5)

• The refresh token grant type allows Clients to obtain a new access token without requiring the resource owner to re-authenticate.
• After the initial authentication and token issuance, the Client receives both an access token and a refresh token.
• When the access token expires, the Client can use the refresh token to request a new access token from the authorisation server.
• This is useful to obtain long-lived access to resources without requiring the user to provide their credentials again.

Step-by-step guide

Step 1 - Generating Access token and Refresh token

The Client sends a POST request to generate a token:

curl -X POST \
  https://gw.us.demystdata.com/oauth/token \
  -d 'grant_type=password&client_id=DEMYST_GENERATED_ID& \
                          client_secret=DEMYST_GENERATED_SECRET& \
                          username=CLIENT_PROVIDED_USER& \
                          password=CLIENT_PROVIDED_PASS'

Demyst will issue an Access token (API Key) with a TTL of 10 minutes, as well as a Refresh token:

# Sample Response
{
  "token_type": "Bearer",
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_at": "2022-11-17T15:29:38.721873Z",
  "refresh_token": "xxxxxxxx"
}

Step 2 - Generating Access token using Refresh token

The Client sends a POST request containing a Refresh token from the above steps:

curl -X POST  
  <https://gw.us.demystdata.com/oauth/token>  
  -d 'grant_type=refresh_token&client_id=DEMYST_GENERATED_ID&  
                               client_secret=DEMYST_GENERATED_SECRET&  
                               refresh_token=REFRESH_TOKEN_FROM_ABOVE'

Demyst will return the Access token (API Key) + Refresh token as specified above:

# Sample Response
{
  "token_type": "Bearer",
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_at": "2022-11-17T15:39:38.721873Z",
  "refresh_token": "xxxxxxxx"
}

Step 3 - Use the Access token to get data

In the last step, you will provide the Access token as the API Key in the request with your channel/Data API to get the data.

curl -X POST  
  <https://gw.us.demystdata.com/v2/channel>  
    -H 'Content-Type: application/json'  
    -d '{  
    "api_key": "ACCESS_TOKEN_FROM_ABOVE",  
    "id": 1020,  
    "inputs": {  
    }  
}'

Errors

Here are some common errors you might see when setting up the OAuth in your application.

Invalid token - If you supply an incorrect token to the API Key in the call to get the data, you will receive an HTTP error code of 403 with the below error:

{  
    "transaction_id": "694c9505-43bf-46cb-94d1-09f5a3b41b4c",  
    "error": {  
        "type": "unable_to_verify_jwt_token",  
        "message": "We could not verify the api token."  
    }  
}

Token expiration - Sending an expired token will also result in an HTTP error code of 403 with the below error. The TTL for the Access token is 10 minutes:

{  
    "transaction_id": "7047ad96-150b-47c7-8baf-0c304cc47491",  
    "error": {  
        "type": "jwt_token_expired",  
        "message": "The api token is expired."  
    }  
}

Channel access denied - The Oauth is set for a particular channel/Data API. If the channel is not enabled for OAuth and you try to use the authentication on it, you will get an HTTP error code of 403 with the below error message:

{  
    "transaction_id": "5696aadd-ce83-4397-a8f6-845d50c1f202",  
    "error": {  
        "type": "channel_access_denied",  
        "message": "API key has no access to channel 366"  
    }  
}

Setup for Clients

OAuth setup will take 5-10 business days depending on the availability of the input request items.

Resource owner's credentials - The end user's username and password should be secretly shared with Demyst to set up OAuth. Demyst recommends sharing two sets, one for evaluation (testing and UAT) and another for production.

Channel ID/Data API - The client will need to share with Demyst the Data API/Channel IDs for which they want OAuth authorisation to be enabled. Only channels added by Demyst will work with OAuth authorisation, otherwise, a channel access denied error message will be returned.

Once the details are sent to the Demyst Platform Engineering team, they will provide the Client with a Client ID and Client secret upon completion of the request. If two sets of user credentials were provided, Demyst will also provide two sets of Client credentials for the two different environments and usage. If needed, Demyst can add more channels/Data APIs for the OAuth Authorisation at a later time that will use the same sets of user and Client credentials.