Authenticating and making your first request

Summary

To make a request to the Firmhouse API you need to set up authentication. Requests to our API are authenticated via an access token that you can generate in your project settings. An access token needs to be included in the HTTP headers of every call you make to our API. For security, each API access tokes has its own permission scope and can be revoked via your project settings.

Generating an API access token

To generate an API access token, go to the Integrations tab in your project, and click the "Generate new token" button:

Viewing Access Tokens on the Integrations page of a Firmhouse project

In the New project access token dialog, you can now choose the Access type for the token you want to generate:

Currently we distinguish two access types:

  • Read - Tokens with the read access type allows the token to read all data from the Firmhouse project it is created for.
  • Create subscription - Tokens with the create subscription access type can only create new subscribers and initiate new checkouts into your Firmhouse project. But they cannot read any data from your project. This can be useful if you want to build a JavaScript frontend application where the token will be visible for visitors of your application.

For the purpose of this guide, choose the Read access type and press Create project access token to generate the token.

Testing a request with Curl

Let's use Curl on the command line to verify if you can query the API successfully with your generated access token. We'll be executing a GraphQL query getCurrentProject to fetch the name of your project.

Open up your favorite terminal app and execute:

$ curl -H 'X-PROJECT-ACCESS-TOKEN: xxx' \
  -X POST \ 
  -d 'query={ getCurrentProject { name } }' \
  https://portal.firmhouse.com/graphql

This should return the following JSON with your project name in the name attribute.

{
  "data": {
    "getCurrentProject": {
      "name":"Firmhouse Stripe Test Plan-based"
    }
  }
}

Testing a request with GraphiQL

Curl is convenient as it is available on most operating systems by default. But testing, iterating, and troubleshooting the API is kind of tedious via Curl. A much more convenient way is using the GraphiQL client. The advantage of using GraphiQL is that it also includes an API explorer with all possible queries, mutations, and data types in the Firmhouse API.

Take a look at the API Reference page for instructions on where to download GraphiQL and how to set it up.

Then in GraphiQL, you can perform the same getCurrentProject query and see it's results:

getCurrentProject query in GraphiQL