> For the complete documentation index, see [llms.txt](https://docs.parameter1.com/basecms-graphql/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parameter1.com/basecms-graphql/connecting-to-the-api.md).

# Connecting to the API

How to use the GraphQL Playground client to connect to the BaseCMS GraphQL API.

## Overview

*For a high-level overview of GraphQL and connection information, review the* [*Getting Started*](/basecms-graphql/master.md) *section.*

In this guide, we'll be using the [GraphQL Playground](https://github.com/graphql/graphql-playground) client. You can feel free to use any API client but we think the GraphQL Playground has the best native autocompletion and schema visibility. Other commonly used clients are [Insomnia](https://insomnia.rest/), [Altair](https://altair.sirmuel.design), or [Postman](https://www.postman.com/).

{% hint style="info" %}
You'll need the following information to query the API:

* An API URL
* A Tenant Key

If you're missing any of this information, please reach out to <support@parameter1.com> and we'd be happy to provide it!
{% endhint %}

To get started, open the GraphQL Playground client and select New Workspace. Select the option to use a URL endpoint, and input your API URL:

![Creating a new workspace in the GraphQL Playground client](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MXgjYT0CWiykOnkxwLP%2F-MXgpFyQGALKz8jW5JYY%2Fnew-workspace.png?alt=media\&token=ead9ec7b-a43f-48e8-b3be-e0348c7798be)

Once you click open, your workspace will open up. Before you can make any queries against the API, you need to identify your tenant. To do so, add the `x-tenant-key` header to your client's configuration. In the GraphQL Playground, you can add that to the "HTTP Headers" tab:

![Setting the tenant key header and a basic "ping" query.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MXgjYT0CWiykOnkxwLP%2F-MXgplx1URT2RynszGmV%2Ftenant-key.png?alt=media\&token=729fb155-f783-417d-80f7-6eff9c737010)

{% hint style="info" %}
Now that you've configured your API client, you can use a feature of GraphQL called introspection. Introspection allows you to browse the schema from your client, without access to the underlying codebase. To browse the schema, you can use the "Schema" (Raw output) or "Docs" (searchable, with comments) tabs on the right side of the screen.
{% endhint %}

## Authenticating to the API

*For a high-level overview of the authentication process, review the* [*Modifying data: Introduction*](/basecms-graphql/modifying-data/introduction.md) *guide.*

In order to modify data via the GraphQL API, you must be authenticated with a valid user token. To obtain this token, send a request to the `login` mutation, supplying your BASE username and password.

![The \`login\` mutation response after supplying a username and password.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfDslQGKPpgpLa2h72H%2F-MfDuDkmNgySR-2tS9Zl%2Fimage.png?alt=media\&token=732e324e-f025-45e4-905d-fb3815883c14)

The returned token should be presented via the `Authentication` header with a `Bearer` prefix.

![The \`activeUser\` query when supplied a valid authentication token.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfDslQGKPpgpLa2h72H%2F-MfDuyaO1Q7wOg5csaeD%2Fimage.png?alt=media\&token=42687811-0f6b-4dc0-85a5-beab618cfb8f)

## Specifying your BASE instance

In order to use certain mutations that modify data, you will need to specify your BASE instance URL. You can do so by including the URL in the `x-base4-api-uri` HTTP header.

![Including the BASE instance URI header in GraphQL Playground.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MfF199p62TvB8XJvixy%2F-MfF1hPvPSLfpGbLVfGo%2Fimage.png?alt=media\&token=e6b04e08-8be8-4d13-ac31-fd5264d53993)