---
title: "Authenticate"
description: "Pass credentials to a provider, and limit what they can do."
canonical_url: "https://docs-oquac2tli-poetry.vercel.app/guides/authentication"
---
# Authenticate

> Pass credentials to a provider, and limit what they can do.

Every provider takes an `auth` option. The accepted types differ by forge, so check the [provider page](https://docs-oquac2tli-poetry.vercel.app/providers) for yours.

## Use a token

Most forges accept a token:

```ts
import { gitlab } from 'forges/gitlab'

const forge = gitlab({
  auth: { type: 'token', token: process.env.GITLAB_TOKEN! },
}).create()
```

The other types are `basic` for a username and password, `app` for GitHub App and Cursor Origin App credentials and `app_password` and `oauth` on Tangled.

## Read without credentials

Leave out `auth` for an anonymous provider. It sends no credentials and makes public reads only. Writes, notifications and subscriptions report `false`:

```ts
import { github } from 'forges/github'

const publicGitHub = github({}).create()
```

## Limit a credential to reads

Set `readOnly: true` to use a credential for reads only. Every write reports `false` and rejects with `ReadOnlyError`. This includes `provider.request()` with a method other than `GET`, `HEAD` or `OPTIONS`:

```ts
import { gitlab } from 'forges/gitlab'

const audit = gitlab({
  auth: { type: 'token', token: process.env.GITLAB_TOKEN! },
  readOnly: true,
}).create()
```

Pass `mutates: false` to `provider.request()` for a request that only reads, such as a GraphQL query.

<warning>

The guard relies on the caller's declaration. It doesn't restrict the credential's permissions on the forge, so create a read-only token as well.

</warning>

## Show the scopes an operation needs

`provider.scopesFor(verb)` returns the token scopes or app permissions that an operation needs on that forge. Use it for a consent screen or an error message:

```ts
const needed = forge.scopesFor('threads.merge')
```

The result has optional `token`, `permissions` and `note` fields. A verb with no mapping returns an empty object.

## Authenticate as a GitHub App

Pass the app ID, the private key and an installation:

```ts
const app = github({
  auth: {
    type: 'app',
    appId: 123456,
    privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
    installationId: 7890,
  },
}).create()
```

The provider mints and caches installation tokens as it needs them. The [GitHub provider page](https://docs-oquac2tli-poetry.vercel.app/providers/github#authentication) explains how to work with several installations.


## Sitemap

See the full [sitemap](https://docs-oquac2tli-poetry.vercel.app/sitemap.md) for all pages.