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.
To generate an API access token, go to the Integrations tab in your project, and click the "Generate new token" button:
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:
For the purpose of this guide, choose the Read access type and press Create project access token to generate the token.
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:
This should return the following JSON with your project name in the name attribute.
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: