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.