Lexicon Garden

dev.cocore.devicePair.start

Begin a device-pairing flow (OAuth 2.0 device-authorization style). Returns a `deviceId` plus a short human-typable `userCode` and the `verificationUri` where a signed-in user approves the pairing. The caller then polls `dev.cocore.devicePair.poll` until approval. The optional input lets an application (rather than a provider machine) say who it is: `appName` is shown on the approve screen, `keyName` names the minted API key so the user can recognise and revoke it, and `returnUrl` is where the approve screen sends the browser afterwards. `returnUrl` is honoured only for hosts the deployment allowlists; anything else is dropped silently, never rejected.

Repository @cocore.dev did:plc:5quuhkmwe2q4k3azfsgg7kdz namespace authority
Details · procedure
Kindprocedure
AuthoritydevicePair.cocore.dev
Indexed
Compare Edit in builder → Fork →

Procedure

procedure · POST

Input

application/json

appDid

string · did

The requesting application's DID. When present the AppView reads the app's `dev.cocore.app.registration` record: the approve screen shows that record's `name` (the `appName` field is ignored) and `returnUrl` is honoured only if it matches one of the record's `returnUrls` AND the return host proves ownership via `/.well-known/cocore-app.json`. A DID with no registration record is rejected with InvalidRequest (AppNotRegistered).

appName

string

Human name of the requesting application, shown on the approve screen.

  • maxLength: 40

keyName

string

Name for the API key minted on approval.

  • maxLength: 100

returnUrl

string · uri

Where to send the browser after approval. Must be https and on an allowlisted host.

  • maxLength: 2000

Output

application/json

deviceId

requiredstring

expiresInSecs

requiredinteger

Seconds until this pairing attempt expires.

pollIntervalSecs

requiredinteger

Minimum seconds between poll calls.

userCode

requiredstring

Short code the user types at the verification URI.

verificationUri

requiredstring · uri

Errors

RateLimited

Too many pairing attempts from this client; retry later.

InvalidRequest

`appDid` is not a DID, or has no `dev.cocore.app.registration` record (message begins `AppNotRegistered`).

Similar lexicons

semantic match

Lexicons whose schemas describe something close to this one. Check them before publishing a new one that overlaps.

  • dev.cocore.devicePair.confirm

    procedure

    Approve or deny a pending device-pairing attempt, identified by the `userCode` the device displayed. Called from the verification UI by a signed-in user. Approving requires the provider `session` to grant to the device. When the requester supplied an allowlisted `returnUrl` at `start`, an approval echoes it back so the verification UI can send the browser there.

  • dev.cocore.devicePair.describe

    query

    Describe a pending pairing attempt by its `userCode`, so the approve screen can say who is asking and for what. Public: it only echoes what the requester supplied at `start` (application name, key name, return URL) plus the attempt's status and remaining lifetime. It never returns the `deviceId` or a session.

  • dev.cocore.devicePair.poll

    query

    Poll a device-pairing attempt by `deviceId`. While the user has not acted, returns `pending`. On approval, returns `session` together with the granted provider session. Terminal negative states are `denied`, `expired`, and `consumed`. An unknown `deviceId` is `unknown`.

  • dev.cocore.app.registration

    record not from the namespace authority

    How an application announces itself to co/core so it can connect users' accounts with one click ("Sign in with co/core"). Published by the application on ITS OWN account (a did:plc or did:web with a repo), one record per DID at rkey `self` — there is no central app registry. When the app calls `dev.cocore.devicePair.start` with `appDid`, the AppView reads this record from the app's PDS: `name` is what the approve screen shows, and `returnUrls` are the only places the approve screen may send the