The TARTLE Authorization Flow

Once you have created a client and associated data packets with it, you're ready to implement the flow to request access to a TARTLE user's DataVault and push data onto those packets. You will need the following:

  • A page on your site or app where you will use a TARTLE DataVault Connect button (a styled link) to start the flow, using your authorization url.
  • A callback endpoint that will receive the redirect from the flow, verify and exchange the code for an access and refresh token pair.

Add the button to your site

The DataVault Connect button is a styled link (<a>) that you can use to start the authorization flow. the url attribute of the link will point to the TARTLE authorization page. The button will look like this:

DataVault Connect

There are several ways to add this button to your site, follow one of them to continue.

Use a script tag

Learn how to add the DataVault Connect button via a script

Read more

Use a manual approach

Learn how to add the DataVault Connect button manually

Read more

Use a React component

Learn how to add the DataVault Connect button using a React component

Read more

Handle the redirect

After the user authorizes your application from our DataVault Connect page, they will be redirected to the redirect_uri set in your client's settings.

You must implement an endpoint for this callback url. This endpoint will be called in the following form:

https://your-callback-url?code=<code>&state=<state>
  • Name
    code
    Type
    string
    Description

    You will use this authorization code to call our token endpoint to exchange for an access and refresh token pair.

  • Name
    state
    Type
    string
    Description

    Used to prevent CSRF attacks. Will be the value you used when constructing the authorization url. See our Security Guide for more information.

Exchange tokens

Once you have received the authorization code, you can exchange it for an access and refresh token pair by calling our /oauth/token endpoint.

Exchanging the authorization code for an access and refresh token pair

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "'$OAUTH_CODE'",
    "code_verifier": "'$CODE_VERIFIER'",
    "client_secret": "'$CLIENT_SECRET'",
    "client_id": "'$CLIENT_ID'",
    "redirect_uri": "'$REDIRECT_URI'",
    "state": "'$STATE'"
  }' \
  https://source.tartle.co/oauth/token
  • Name
    grant_type
    Type
    string
    Description

    This is a standard OAuth 2.0 parameter, set it to authorization_code when exchanging the authorization code for an access and refresh token pair.

  • Name
    code
    Type
    string
    Description

    The authorization code you received from the redirect.

  • Name
    code_verifier
    Type
    string
    Description

    The code verifier you used when constructing the authorization url. See our Security Guide for more information.

  • Name
    client_secret
    Type
    string
    Description

    The client secret you saved somewhere when you created the client. This was only available to you at the time of creation and should be stored securely. See our Security Guide for more information.

  • Name
    client_id
    Type
    string
    Description

    The client id you received when you created the client and you can find it in your developer settings.

  • Name
    redirect_uri
    Type
    string
    Description

    The redirect uri you used when you created the client and you can find it in your developer settings.

  • Name
    state
    Type
    string
    Description

    The state you used when you constructed the authorization url. See our Security Guide for more information.

You will receive a JSON response with the following properties

Response

{
  "access_token": "<your_access_token>",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "<your_refresh_token>",
  "scope": "push_packet",
  "created_at": "<timestamp>"
}
  • Name
    access_token
    Type
    string
    Description

    Use in the Authorization header to push data to the data packets associated with your client. It is valid for 24 hours. After that period, you can use the refresh_token returned in the response to exchange for a new access token.

  • Name
    refresh_token
    Type
    string
    Description

    When your access token expires, you can call the /oauth/token endpoint to exchange it for a new access token. After the exchange, this token will be revoked, so make sure you save the new refresh token returned in the exchange response.

To exchange an access token for a refresh token, you would use the same /oauth/token endpoint you used to exchange the authorization code but with the following body:

Request body

{
  "grant_type": "refresh_token",
  "refresh_token": "<your_refresh_token>",
  "client_secret": "<your_client_secret>",
  "client_id": "<your_client_id>",
  "redirect_uri": "<your_redirect_uri>"
}

The response will be in the same format as before. You need to make sure you save the new refresh token returned in the exchange response, as the old one will be revoked.

Congratulations! You have successfully implemented the authorization flow and are ready to begin pushing data packets to your users' DataVaults.

Was this page helpful?