# GitHub and Vercel

Use trusted workload identity for short-lived project access.

<a id="guide-content"></a>



<a id="workloads"></a>

### GitHub Actions and Vercel previews

An organisation owner configures a workload binding in Credentials for a dedicated test project. Members can inspect trust. These integrations exchange platform identity for an InboxSpec key lasting at most five minutes; no standing InboxSpec secret needs copying between platforms. Grants reach the whole dedicated project, with inbox and message test permissions, and cannot administer keys, domains, webhooks or memberships. Revoking a binding immediately revokes its issued keys.

For GitHub, use the authentication Action from the reviewed private release or source directory `.github/actions/inboxspec-auth`. Bind the exact subject, immutable repository and owner IDs, branch ref and workflow ref, plus environment if used. Pin and review the workflow and Action. Only trusted branch push/manual-dispatch contexts are accepted; pull requests, tags and workflow\_run are denied.

```yaml
permissions:
  contents: read
  id-token: write
# After trusted checkout and installing the reviewed CLI:
steps:
  - uses: ./.github/actions/inboxspec-auth
    with:
      api_url: ${{ vars.INBOXSPEC_API_URL }}
      binding_id: ${{ vars.INBOXSPEC_GITHUB_BINDING_ID }}
  - run: inboxspec auth check --json
```

This is a job fragment, not a complete workflow. The Action obtains identity, masks the exchanged key, and exports API configuration for subsequent steps. Run fixture setup and the mail test immediately; acquire a fresh identity for another grant after expiry.

For Vercel, trust an exact team, project, subject and preview environment, including immutable IDs. All code with that project’s preview identity can request a grant; use a dedicated project whose preview code is trusted. Production and local development identities are rejected. Configure non-secret `INBOXSPEC_API_URL` and `INBOXSPEC_VERCEL_BINDING_ID`.

```typescript
import { getVercelOidcToken } from "@vercel/oidc";
import { inboxSpecFromVercel } from "@inboxspec/sdk";
const { client, expiresAt } = await inboxSpecFromVercel({
  apiUrl: process.env.INBOXSPEC_API_URL!,
  bindingId: process.env.INBOXSPEC_VERCEL_BINDING_ID!,
  getToken: getVercelOidcToken,
});
```

Use `@vercel/oidc` 3.7 or newer in server-side preview builds/functions. The adapter requests a custom audience and fresh JTI. Reuse the client only until expiry; a fresh grant requires fresh identity. Do not return credentials or provider tokens to a browser. Marketplace installation and public npm distribution are not required for this flow and are not currently offered.