Securely accessing RavenDB / RavenHQ over HTTP

I want to use a RavenDB database hosted in the cloud by RavenHQ from a NodeJS app. I didn’t find a JavaScript client or NPM package that looked very mature, so I looked into straight HTTP API access. This took me a little time to figure out – I wasn’t able to find a step-by-step guide, so here’s one:

1. Get an API key from the RavenHQ website.

I guess they’re GUIDs. They’re straightforward to set up and configure with the access you’d like. Let’s pretend mine is 19ecad1c-d90e-4a98-a2e7-e79f40881cef.

 

2. Hit the OAuth server to exchange your API key for an access token.

Make an HTTP GET request to the following URL. Include the two headers shown.

  • HTTP GET https://us-oauth-1.ravenhq.com/ApiKeys/OAuth/AccessToken
  • Api-Key: 19ecad1c-d90e-4a98-a2e7-e79f40881cef
  • grant_type: client_credentials

You should get back a JSON document that looks something like this:

{ 
   Body: "{\"UserId\":\"19ecad1c-d90e-4a98-a2e7-e79f40881cef\",\"AuthorizedDatabases\":[{\"Admin\":false,\"TenantId\":\"your-database\",\"ReadOnly\":false}],\"Issued\":63504123456789.6}", 
   Signature: "ABigLongNastyBase64Thing=" 
} 

 

3. Access your RavenHQ server with the appropriate Authorization Header.

Now you should be able to use the HTTP API as documented, including the entire access token from the previous step in an Authorization header, like this:

  • HTTP GET https://yourbird.ravenhq.com/databases/your-database/docs
  • Authorization: Bearer {“Body”:”{\”UserId\”“, Signature: “ABigLongNastyBase64Thing=“}

To be clear, after the word “Bearer” and a space goes the entire JSON document you got back from the OAuth server, encoded as a string.

When you issue this request you should get an HTTP 200 response with JSON content matching what’s in your database.

 

4. Expiration

When the token expires your request will get a 401 Unauthorized response. Here are some of the interesting response headers that you’ll also get:

  • OAuth-Source: https://us-oauth-2.ravenhq.com/ApiKeys/OAuth/AccessToken
  • WWW-Authenticate: Bearer realm=”Raven”, error=”invalid_token“,error_description=”The access token is expired

With this information you can detect that your token has expired and get a new one per Step 1 above.

This entry was posted in JavaScript, JSON, RavenDB, REST. Bookmark the permalink.
  • Zacharias Thompson

    Great source of info. Thanks!

  • Fish

    Thanks Jason, wouldn’t have figured this out without your post!

    Took a bit of trial and error but finally managed to get it working with PowerShell using the following, thought others might find this useful.

    – Powershell start –
    function ravenAccessToken
    {
    $url = “https://us-oauth-1.ravenhq.com/ApiKeys/OAuth/AccessToken”
    $apiKey = “65449a84-5156-4614-bffc-98d57b4d95a1″
    $headers = @{“grant_type” = “client_credentials”; “Api-Key” = $apiKey;}
    return Invoke-RestMethod -Uri $url -Headers $headers -Method Get
    }

    function ravenPut
    {
    $authorization = ravenAccessToken | ConvertTo-Json
    $authorization = “Bearer ” + $authorization
    $authorization = $authorization.replace(“`n”, ” “).replace(“`r”, ” “)
    $url = “https://kiwi.ravenhq.com/databases/your-database/docs”
    $data = “{ FirstName: ‘Bob’, LastName: ‘Smith’, Address: ’5 Elm St’ }”
    $headers = @{“Authorization” = $authorization}
    return Invoke-RestMethod -Uri $url -Body $data -Headers $headers -Method Put
    }
    – Powershell end–

    • pettys

      Nice! Thanks, Fish!