Authentication

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.

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:

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. SDL does not describe authentication. Add provider and login settings through the same shared auth configuration used for OpenAPI.

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. 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 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:

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 for your own account system.

Choose the customer experience

parcel login
parcel whoami

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:

{
  "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 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 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.