Skip to main content

Making our first request

Before we can explore Scrive Flow, we need to be sure that we are able to properly authenticate requests to the Flow API.

In this tutorial, we will be calling the /experimental/flow/drafts endpoint. This will most likely return an empty list ([]) for you, but it will mean that we've sent a request that was successfully authenticated and received a valid response.

Getting the authentication tokens​

Firstly, we will need to get some OAuth tokens for use with the Scrive API. We can authenticate with Scrive's APIs using either OAuth or via the session cookie received when logging into the web application. For simplicity, we'll only cover the OAuth method here.

We will be using the scrive.com environment for our testing here. However, these steps should work on any of Scrive's environments, including the main production environment.

Firstly, let's open up a shell and set some local variables with the host, and our username and password:

note

By convention, $ at the beginning of the line refers to a shell prompt. You should not paste this character into your terminal.

# Change the user email and password to your own
# scrive.com user account
$ base_url="https://scrive.com"
; user_email="demo@scrive.com"
; user_password="password123"

Next, we need to get our OAuth credentials by calling the /api/v2/getpersonaltoken endpoint. This is not a part of the Flow API, but the regular Scrive API and the Flow API share common authentication mechanisms.

$ curl -X POST "${base_url}/api/v2/getpersonaltoken" \
  --data-urlencode "email=${user_email}" \
  --data-urlencode "password=${user_password}"

We should see a successful response containing something like the following:

{
  "apitoken": "3e6170e649b084ea_1",
  "apisecret": "03460c00dc86d756",
  "accesstoken": "0f081cdc6c0145c8_1",
  "accesssecret": "3b645a8d97d78b72"
}

Building the authentication header​

These values are our OAuth tokens, and we will use them to authenticate with the API from now on. Using them, we can construct an OAuth 1.0 Authorization header:

$ apitoken="3e6170e649b084ea_1"
; accesstoken="0f081cdc6c0145c8_1"
; apisecret="03460c00dc86d756"
; accesssecret="3b645a8d97d78b72"

$ auth_header="Authorization: oauth_signature_method=\"PLAINTEXT\", \
  oauth_consumer_key=\"${apitoken}\", \
  oauth_token=\"${accesstoken}\", \
  oauth_signature=\"${apisecret}&${accesssecret}\""

Making the request​

This will be sent as a HTTP header when we make requests to the API:

$ curl -i -H "${auth_header}" "${base_url}/experimental/flow/drafts"

I included the -i flag above so that it would display the HTTP response headers. We should see something similar to the following:

HTTP/2 200
server: nginx
date: Wed, 24 Feb 2021 13:00:32 GMT
content-type: application/json;charset=utf-8
vary: Accept-Encoding
strict-transport-security: max-age=31536000
p3p: CP="NOI ADM DEV COM NAV OUR STP"

[]

The important part of this is HTTP/2 200 and the JSON list which is returned. Your list may not be empty if you have already created flow drafts via the web application. As long as you received a 200 response and a JSON list, empty or otherwise, then you have successfully authenticated.

If you see something like the following (with 401 code) then you have likely made a mistake and should go through these instructions again:

HTTP/2 401
server: nginx
date: Wed, 24 Feb 2021 13:05:00 GMT
content-type: application/json
strict-transport-security: max-age=31536000

{
  "code": 401,
  "message": "Authentication Error",
  "explanation": "Cannot parse OAuth header",
  "details": null
}

Further Reading​

If you would like a deeper knowledge of the topics covered here, then the following articles may be useful. You are not required to read them in order to understand the rest of this guide.