---
title: "Authentication"
description: "Configure customer sign-in for generated tools and runtime credentials for SDK applications."
url: https://typeship.dev/docs/authentication
markdown: https://typeship.dev/docs/authentication.md
section: "Authentication"
---
> ## Documentation index
> Fetch the documentation index at https://typeship.dev/llms.txt or every prose page and both generated references at https://typeship.dev/llms-full.txt.
> Append .md to any prose docs URL, or send Accept: text/markdown, for the markdown twin of that page.
> Select existing code examples with Accept-Code-Language: typescript, python, or go (one value), or add ?codeLanguage=python to a Markdown URL. The query parameter takes precedence. Unsupported values return the full docs with a notice.

# Authentication

Configure customer sign-in for generated tools and runtime credentials for SDK applications.

Authentication lets a generated Target call protected operations on your API. You define the accepted credentials and sign-in flow; Typeship generates the client code, and your API enforces access.

| Credential                | Purpose                                                                                                   |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| Typeship login or API key | Manage Projects and run generation. See [Typeship API authentication](https://typeship.dev/docs/typeship-api/authentication). |
| Definition source headers | Fetch or introspect a protected specification.                                                            |
| Your API's credentials    | Authenticate requests from generated CLIs, MCP servers, and SDKs.                                         |

Configure customer sign-in on the Project for CLI and local MCP Targets. SDK applications provide credentials at runtime. A self-hosted remote MCP server needs its own connection authorization as well as upstream API credentials.

## Start with your API

In OpenAPI, define a scheme under `components.securitySchemes` and reference it from `security`. For an API that accepts bearer tokens:

```yaml
components:
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
security:
  - apiToken: []
```

Use an OAuth scheme to describe your provider's flows and the scopes each operation requires. OpenID Connect metadata can supply a discovery URL; configure the exact issuer and public client ID for browser login. Set `security: []` on a public operation.

For GraphQL, configure the endpoint and security requirements in your [GraphQL Definition settings](https://typeship.dev/docs/guides/graphql). SDL does not describe authentication. Add provider and login settings through the same shared `auth` configuration used for OpenAPI.

| Your API requires            | What to configure                                                             |
| ---------------------------- | ----------------------------------------------------------------------------- |
| Bearer token or API key      | The header or query parameter your API expects.                               |
| Basic authentication         | A Basic scheme; customers supply a username and password together.            |
| OAuth access token           | An OAuth or bearer scheme, your issuer, and an appropriate OAuth application. |
| Either of two credentials    | Separate alternatives in the operation's `security` array.                    |
| Several credentials together | Put those schemes in the same security requirement.                           |

Generated products choose a complete credential combination and send only those credentials. For schemes sharing a header, use their exact scheme names in [named credentials](https://typeship.dev/docs/targets/cli#auth-and-configuration). Cookie-based API-key schemes are not generated authentication options. Review generation warnings for unsupported schemes or omitted operations.

## Configure authentication once

Open **Console → Project → Authentication**. Review the API credentials detected in your Definition, then enable customer sign-in and set your issuer, OAuth application, scopes, and identity read.

The Project owns the OAuth server, application catalog, and identity policy. A Target may select a Project-owned OAuth application, but it cannot override provider endpoints, scopes, or identity rules. Tokens, API keys, refresh tokens, and client secrets stay in the runtime, outside this public configuration.

Saving validates the configuration. After adding an OAuth application, use **Verify setup** to check a saved CLI or MCP Target against your API. Browser verification runs through the generated CLI; a credential check verifies API access without running the provider login. See the [configuration reference](https://typeship.dev/docs/projects/config#authentication) for the public shape.

## Connect your identity provider

Choose the setup for the identity provider your API already trusts. Browser login uses a public OAuth client with PKCE:

- [Clerk](https://typeship.dev/docs/integrations/authentication-providers#clerk): Configure a public OAuth application for browser PKCE and local MCP sign-in.
- [Better Auth](https://typeship.dev/docs/integrations/authentication-providers#better-auth): Configure browser or device login, organization selection, and remote MCP access.
- [WorkOS](https://typeship.dev/docs/integrations/authentication-providers#workos): Connect a public WorkOS Connect application to the generated CLI.
- [Auth0](https://typeship.dev/docs/integrations/authentication-providers#auth0): Use a Native application with PKCE, API audience, and permissions.

Each recipe shows what to create at the provider and how to map it into Typeship. Confirm the discovery metadata, callback URL, scopes, and API audience for your tenant, or use the [custom browser approval contract](https://typeship.dev/docs/guides/browser-login#use-your-own-browser-approval-flow) for your own account system.

## Choose the customer experience

**CLI**

For browser login, register a public OAuth client and configure its exact issuer and loopback callback. The generated CLI uses Authorization Code with PKCE; it contains no client secret. The following commands illustrate a CLI named `parcel` for the fictional Parcel API. Your command name comes from the generated README:

```bash
parcel login
parcel whoami
```

The browser handles sign-in and consent. Configure an API identity read so login verifies the returned account before saving the session. Follow [Add browser login](https://typeship.dev/docs/guides/browser-login) for setup.

For a remote terminal, use device authorization when your provider supports it. `login --no-browser` prints the normal browser-login URL for a browser on the same computer; it does not turn a localhost callback into a remote login flow.

Without OAuth or custom approval settings, `login` offers a hidden credential prompt. In CI, supply the credential through the generated environment variable and your CI secret store. Explicit credentials take precedence over a saved login.

**Local MCP**

A local MCP process can reuse a compatible CLI profile. The command name, configuration directory, storage choice, API destination, and authentication settings must match. The server reads the current session on tool calls, coordinates OAuth refresh with the CLI, and picks up login and logout without restarting.

Customers can also supply environment credentials for the server. A complete explicit credential combination takes precedence over the saved profile. Keep credentials in the process environment or local store; do not paste them into an agent conversation.

See [local MCP authentication](https://typeship.dev/docs/targets/mcp#stdio) and [separate profiles](https://typeship.dev/docs/targets/cli#use-separate-profiles).

**Remote MCP**

A remote server needs two distinct permissions: permission for the caller to connect to MCP, and permission for that caller's actions to reach your API.

The generated HTTP handler validates connection tokens against its configured MCP issuer, resource, and scopes. Your application supplies separate API credentials through `credentialsFor(principal)`. It owns account linking, credential storage, refresh, and revocation. The handler does not forward the MCP connection token as an API credential or read a local CLI profile.

If an API account needs linking, your resolver can return a browser interaction through `McpAccountLinkRequired`. Your application must verify the user, bind the link to that user and client, and obtain API authorization. A client acknowledging the prompt cannot grant access.

The generated handler validates signed JWTs by default. For opaque tokens, configure [server-side introspection](https://typeship.dev/docs/targets/mcp#opaque-access-tokens) so your provider checks each connection token. Self-hosted deployments resolve upstream credentials with application-owned account linking. The Typeship-hosted endpoint instead accepts a caller-supplied API credential and does not apply `mcp.access`. Follow [remote MCP setup](https://typeship.dev/docs/targets/mcp#streamable-http) before choosing a deployment.

**SDKs**

The application using your SDK supplies credentials. This example uses the fictional Parcel API and an illustrative local package named `parcel-client`:

```ts
import { ParcelClient } from "parcel-client";

const client = new ParcelClient({
  bearerToken: process.env.PARCEL_CLIENT_TOKEN!,
});
```

Use a credential callback when your application manages expiring tokens. TypeScript, Python, and Go SDKs also support server-side client-credentials grants with cached access tokens. The selected OAuth application supplies public defaults; the application supplies the secret at runtime.

SDKs do not open a login browser or read a CLI profile. Keep confidential client secrets in server applications. See [SDK authentication](https://typeship.dev/docs/targets/sdk#authentication) for the language-specific options.

## Verify the account and permissions

Choose an authenticated REST GET or GraphQL query that runs without arguments and identifies the caller. Map its subject, account, or organization fields under `identity_verification`.

For example, an API returning `{"id":"user_123","account_id":"acct_123"}` can use:

```json
{
  "auth": {
    "identity_verification": {
      "operation": "me.get",
      "subject_field": "/id",
      "account_field": "/account_id"
    }
  }
}
```

Use the generated operation name shown in the Console. Login then checks that the API rejects anonymous access and accepts the new credential for the intended identity. Refresh verifies that identity again before saving replacement tokens. A failed login leaves the previous session in place.

Your customer can require an expected identity with `parcel login --account acct_123`. The corresponding `--organization` flag checks the API's result. If your provider supports an organization parameter, you can enable `--login-organization` to request and verify a particular organization. Configure [organization selection](https://typeship.dev/docs/projects/config#let-customers-choose-an-organization) for your provider's browser flow.

Make a read request for the intended account, and confirm that another account and an operation outside the grant's scope are denied. Your API must enforce these rules on every request. A successful identity read does not prove every permission.

Use **Verify setup** in the Console to confirm that anonymous access is rejected, the credential is accepted, and the identity response matches the expected account. For browser OAuth, download the one-time check and run it with the generated CLI. Refresh tokens remain on that computer; Typeship does not save the submitted credential, expected ID, or API response body.

## Keep sessions under control

The CLI encrypts saved sessions with an OS-protected key by default. It stops if secure OS storage is unavailable; plaintext file storage requires an explicit choice. See [storage requirements](https://typeship.dev/docs/targets/cli#login-logout-whoami) for platform details.

Profiles separate saved accounts and environments. OAuth sessions are bound to the configured issuer, client, API destination, and login settings. Changing those settings requires another login. The CLI and compatible local MCP coordinate refresh, including rotation; an uncertain refresh requires a new login instead of replaying a possibly consumed token.

`logout` removes the saved session and attempts provider revocation when available. It cannot clear environment credentials or revoke an externally issued pasted key automatically. Check its revocation result and use your provider's credential management when revocation fails. Local deletion does not prove that a remote token is invalid.

For provider prerequisites and configuration recipes, see [Connect your identity provider](https://typeship.dev/docs/integrations/authentication-providers).

## Sitemap

[Documentation index](https://typeship.dev/llms.txt)