# Auth.md — Second Shift authentication

Second Shift serves verified client organizations and external AI agents acting with a client's explicit authority. The Client API is an OAuth 2.0 protected resource.

## Discover

1. Read `https://www.secondshiftagents.com/.well-known/oauth-protected-resource`.
2. Read the authorization server metadata listed there.
3. Read `https://www.secondshiftagents.com/auth.md` and the OpenAPI document.
4. Request only the scopes needed for the current organization and workflow.

Unauthenticated requests to the versioned API return `401` with a `WWW-Authenticate` header pointing to the protected-resource metadata.

## Pick a method

The supported agent method is client-delegated OAuth 2.0 Authorization Code with PKCE. Tokens must use the Second Shift API audience and include the verified organization claim. Dynamic, anonymous, and self-issued client registration are not supported.

## Register

Second Shift does not expose a dynamic client-registration endpoint. A human verifies the organization, workflow scope, billing authority, and intended agent before Second Shift provisions an organization-bound OAuth client. The public workflow preflight is scope intake only; it does not register a client, create an account, issue a credential, start checkout, or authorize a charge.

## Claim

Second Shift does not expose an anonymous credential-claim endpoint. After the organization and agent authority are approved, Second Shift delivers the organization invitation and OAuth client details through verified channels. The agent then completes the authorization flow with the client organization.

## Use credential

Send the access token only to `https://www.secondshiftagents.com/api/v1/`:

```http
Authorization: Bearer <organization-scoped-token>
```

An organization owner grants explicit scopes per workflow. The `approvals:write` scope is revocable and does not permit member management, billing changes, price negotiation, or further delegation.

## Errors

- `401 authentication_required`: discover the protected-resource metadata, obtain a valid token, and retry.
- `403 insufficient_scope`: ask the organization owner for the exact missing workflow scope.
- `404 not_found`: the operation or resource is unavailable to the active organization; the API does not disclose cross-tenant existence.
- `409 conflict`: reconcile the current workflow state or idempotency key before retrying.
- `429 rate_limit_exceeded`: respect `Retry-After` and the RFC RateLimit headers.

All API failures use `application/problem+json` with a machine-readable `code`, human-readable `detail`, and a `resolution`.

## Revocation

The organization owner can revoke the delegated agent or an individual workflow grant at any time. Revoked authority no longer permits API, MCP, WebMCP, or portal-backed actions. Second Shift can also revoke the OAuth client when the relationship or approved workflow ends.

## Scope intake and support

Submit a workflow through the [preflight skill](https://www.secondshiftagents.com/skills/preflight/SKILL.md) or contact [agent@secondshiftagents.com](mailto:agent@secondshiftagents.com). A preflight identifies the organization, contact, workflow outcome, connected systems, sample inputs and outputs, expected volume, approval points, and the requesting agent's billing authority. Do not send credentials or sensitive production records in the initial request.