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.
Who holds which credential
| Who | Credential | Used for |
|---|---|---|
| Your team | Typeship login or API key | Managing your Project and running generation. See Typeship API authentication. |
| Your team | Spec source headers | Fetching or introspecting a protected API spec. Typeship stores them write-only and never places them in generated packages. |
| Your customers | Your API's own credentials | Authenticating requests from the generated CLI, MCP server, and SDKs. |
Your customers never need a Typeship sign-in or credential. Generated packages call your API with credentials your API issues and enforces. When a customer connects through a Typeship-hosted MCP endpoint, Typeship forwards their API credential with each request and does not store it.
Start with your API
In OpenAPI, define a scheme under components.securitySchemes and reference it from security. For an API that accepts bearer tokens:
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 Spec settings. 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. Consult each generated Target's authentication options when several schemes share a header. Cookie API keys and other HTTP schemes such as Authorization: Token <key> are supported; customers supply only the key. Mutual TLS and HTTP Digest are not generated authentication options. Review generation warnings and Diagnostics for unsupported schemes.
Supported authentication
Each row is a way your API can authenticate its users. Each column is a generated product.
| Your API accepts | CLI | Local MCP server | Typeship-hosted MCP | Self-hosted MCP | SDKs |
|---|---|---|---|---|---|
| Bearer token | Flag, environment variable, or login | Environment | Caller sends Authorization | Your application supplies it | Constructor option or callback |
| API key in a header or query parameter | Flag, environment variable, or login | Environment | Caller sends the declared header | Your application supplies it | Constructor option or callback |
API key in a cookie, or another HTTP scheme such as Authorization: Token <key> | Flag, environment variable, or login | Environment | Caller sends the Cookie or Authorization header | Your application supplies it | Constructor option or callback |
| HTTP Basic | Flags or environment variables | Environment | Caller sends Authorization: Basic | Your application supplies it | Username and password |
| OAuth, signed in by a person | Browser login; device login when a device endpoint is declared | Environment credentials | MCP OAuth after you verify your origins | MCP OAuth, then your application supplies API credentials | Pass the access token, a callback, or a refresh token (refreshToken) |
| OAuth client credentials, when the Spec declares that flow | Not supported | Environment client ID and secret | Not supported | Your application supplies it | clientCredentials option |
| Mutual TLS, HTTP Digest, or request signing | Not supported | Not supported; the operation is refused | Not supported | Your application supplies it | Add it with a custom HTTP client |
Connectors in Claude.ai, Claude Desktop, and ChatGPT cannot send credential headers, so they reach the hosted endpoint only for OAuth APIs. See which clients can connect.
Use API keys and tokens
A bearer token, API key, or Basic scheme declared in your Spec needs no further authentication configuration. Each generated Target accepts the credential your API already issues. The examples use a CLI named parcel for the fictional Parcel API; your command and package names come from the generated README.
CLI
Use parcel login --help for the credentials and login methods your API supports. In CI, supply credentials through the generated environment variables and your secret store. Explicit credentials take precedence over a saved login.
MCP server
Supply credentials to a local MCP server through its generated environment variables. Keep credentials in the process environment; do not paste them into an agent conversation. See local MCP authentication.
A Typeship-hosted MCP endpoint accepts the caller's API credential in the scheme your Spec declares. See Hosted endpoint.
SDKs
The application using your SDK supplies credentials. This example uses an illustrative local package named parcel-client:
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. SDKs do not open a login browser or read a CLI profile. See SDK authentication for the language-specific options.
Add browser login
Browser login lets customers run parcel login and sign in to the account they already have. Their browser handles sign-in and consent, and the CLI verifies the account through your API before saving the session.
Connect your identity provider
Any identity provider that supports Authorization Code with PKCE for a public client and a loopback callback works. The generated CLI contains no client secret. These recipes show what to create at common providers and how to map it into Typeship:
Clerk
Configure a public OAuth application for browser PKCE and local MCP sign-in.
Better Auth
Configure browser or device login, organization selection, and remote MCP access.
WorkOS
Connect a public WorkOS Connect application to the generated CLI.
Auth0
Use a Native application with PKCE, API audience, and permissions.
Okta
Use an OIDC Native Application with a custom authorization server.
Microsoft Entra ID
Register a desktop client and request your API's scopes.
For another provider, follow the provider checklist. For your own account system, use the custom browser approval contract.
Configure sign-in
Open Console → Project → Authentication. Review the API credentials detected in your Spec, then enable customer sign-in and set your issuer, OAuth application, scopes, and identity read. Saving validates the configuration. See the configuration reference for the public shape and Add browser login for a complete walkthrough.
Tokens, API keys, refresh tokens, and client secrets stay in the runtime, outside this public configuration.
Customers then sign in with:
parcel login
parcel whoamiFor 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.
Verify the account and permissions
Choose an authenticated REST GET or GraphQL query that runs without arguments and identifies the caller. Map its user ID (subject_field), account, or organization fields under identity_verification.
For example, an API returning {"id":"user_123","account_id":"acct_123"} can use:
{
"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.
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. A credential check verifies API access without running the provider login. Typeship does not save the submitted credential, expected ID, or API response body.
For a CLI Target with browser OAuth, enter the expected identity and choose Download browser login check. Run the command shown in the Console with your installed CLI on the same computer as the browser. The one-time check expires after 10 minutes and must match the saved Target's authentication settings and Spec. Regenerate and install the CLI if those settings changed.
This check uses a temporary browser login, verifies the identity locally, and sends only its access token to Typeship for an independent API check. Refresh tokens stay local, and the check does not replace your saved CLI session. The CLI attempts to revoke the temporary grant afterward; if revocation fails, revoke it through your provider. The Console reports the result when verification finishes. A failed or expired check needs a new download.
Manage saved sessions
The CLI saves its session in a credentials file readable only by the current user. It honors XDG_CONFIG_HOME. Use environment credentials in automation and config set environment to select an environment declared by your API.
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.
Advanced configuration
Require an account or organization
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 for your provider's browser flow.
Use several OAuth applications
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. Use separate applications when products have different trust requirements, such as a public CLI client and a confidential backend client. See Use more than one OAuth application.
Separate sandbox and production
Environment names come from your Spec's servers. Each environment can select its own OAuth application, scopes, audience, and API resource. See Configure sandbox and production.
Authenticate a machine client
TypeScript, Python, and Go SDKs support server-side client-credentials grants with cached access tokens. The selected OAuth application supplies public defaults; the application supplies the secret at runtime. Keep confidential client secrets in server applications. See Configure a machine client.
Self-host a remote MCP server
Local MCP and the Typeship-hosted endpoint need no additional authorization setup. A remote MCP server you deploy yourself 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 so your provider checks each connection token. The Typeship-hosted endpoint does not apply mcp.access. Follow remote MCP setup before choosing a deployment.
For provider prerequisites and configuration recipes, see Connect your identity provider.