# Getting Started

## Authentication

All calls to the Firmhouse GraphQL API require a valid `X-Project-Access-Token` HTTP header to be passed in every request. You can generate a Project Access Token by going to the **Settings > Integrations** page in your Firmhouse project as a project manager.

### Access Token Types

Each Project Access Token has a specific access type. The access type controls what the token can do (or cannot do) and which data is accessible via the token.

There a currently two access types: **write** and **storefront**. In the near future we will also introduce a **read** type. Read below on the details per access type.

#### **Write**

The write access type gives you full API access to all data. Treat this as an administrative secret that you should not expose to the public. This token can read and modify all data in your project. Always securely embed this token into your application and never expose this token to regular users or the public.

#### **Storefront**

The storefront access type is meant for building Headless applications or storefronts without needing a server-side component in your app. For example in your frontend React application or Apollo JS client. It is safe to expose this token to the public as part of your runtime codebase.

A storefront token will only give limited access to available products and plans. And it allows you to build a cart and initiate a subscription checkout and payment flow. This token does not give you access to subscription data after the subscription has signed up.

## Making calls

The API is exposed on the following endpoint:

```
POST https://portal.firmhouse.com/graphql
```

All calls towards our API should be made with a HTTP `POST`. Your HTTP `POST` should include a valid `X-Project-Access-Token` HTTP header as explained under Authentication.

Certain queries and mutations also need a `X-Subscription-Token` HTTP header to be present, alongside the `X-Project-Access-Token`. This is usually the case when a query or mutation accesses data of an individual subscription.

Calls can be made via standard server-to-server HTTP communication, but also by using Fetch from your customer's browser if you're building a frontend or headless experience without server-side component.

## Clients and libraries

There are several ways and clients that can be used to interact with the API. For example:

* Use a tool such as [GraphiQL](https://github.com/graphql/graphiql) or [Insomnia](https://insomnia.rest/products/insomnia) to interactively explore the API and its documentation.
* Use cURL to manually make calls from the command-line.
* Use the [GraphQL Ruby Client](https://github.com/github/graphql-client) to make calls from a Ruby on Rails app.
* Use [Apollo](https://www.apollographql.com/) when using React, Vue, or Next.js.