# Card links for every app

October 21, 2026 · API · Breaking

Every application can now mint a card link for a person it provisioned and verified. It is how that person adds a card.

## What changed

- **`POST /v1/users/:id/links`** with `{ "purpose": "card" }`, and optionally a `returnUrl` and a `state`, answers `201` with a `url` on `layout.link/h/` and its `expiresAt`. The link works once and must be opened within 15 minutes.
- **The page.** It shows your application's name and logo, says your application partners with Layout and never sees the card, takes a card, Apple Pay or Google Pay, and asks for no Layout sign-in.
- **Return URLs.** Register them on **App details** in the console: `https`, your app's own scheme, or `localhost` for sandbox. The page sends the person back with `status=card_added` or `status=canceled`, and your `state`.
- **A card link only adds a card.** On an account that already holds all the cards it can, it replaces only a card one of your own card links added. Otherwise the page tells the person their account is full, nothing is saved, and going back returns `status=canceled`. It never removes a card the person or another application added.
- **No url on `card_required`.** For a person you provisioned, a build that fails with `no_card` or `card_not_orderable`, and a confirm that answers `build_only` with `card_required`, carry no `url`. Mint a card link instead.

**Update 2026-10-21:** A card link adds only on an account the person signs in to. On an account nobody signs in to, which is every account a verify made, a card link on a full account replaces the default card, and the page names that card before they save. See [What the person sees](https://developer.layout.link/reference/card-links#what-the-person-sees).

```
POST /v1/users/usr_4b8e9a01c2d3/links
{ "purpose": "card", "returnUrl": "com.acme.assistant:/layout/card", "state": "c1f9e2" }

→ 201
{ "url": "https://layout.link/h/3q2Xw7…", "expiresAt": "2026-10-21T17:15:00.000Z", "purpose": "card" }
```

## Why it matters

A person you provisioned has no Layout sign-in to use, so a page that asked for one stopped them. The card link asks for nothing but the card, and brings them back to your app.

## What to do

Register a return URL in the console. When Layout asks for a card, mint a link and open it: as a sheet in an iOS app, in `ASWebAuthenticationSession` or `SFSafariViewController`, or as a link in a chat or text. See [Card links](https://developer.layout.link/reference/card-links).

## Breaking changes

Code that sent `failure.next.url` or `error.next.url` on `card_required` to a person you provisioned gets no url now. Mint a card link for them instead.