Skip to main content

Interactions

A sign-in in progress.

oidc-provider sends the browser to GET /api/v1alpha1/interactions/<name>, setting a cookie scoped to that path; opened in a browser it redirects to the page, /interaction/<name>, and fetched as JSON it is the Interaction.

GET interactions/<name>the interaction
DELETE interactions/<name>cancel: the service is told the person declined
POST interactions/<name>/emailchallengeemail a code and link: { "spec": { "email": "…" } }
POST interactions/<name>/passkeychallengeoptions for the browser: { "spec": { "purpose": "Authenticate" | "Register" } }
POST interactions/<name>/loginsign in, with the code, the link's token, or a passkey
GET, PATCH interactions/<name>/accountthe account that just signed in, while setting it up
POST interactions/<name>/passkeysadd a passkey, answering a Register challenge
POST interactions/<name>/consentthe scopes agreed to: { "spec": { "scopes": ["openid", "email"] } }

Phases

status.phase says what is needed next:

  • LoginRequired — sign in. status.emailChallenge is the email sent, if one was.
  • Authenticated — signed in; status.account is who. Offer to finish setting up, then follow status.returnTo.
  • ConsentRequired — status.consent.scopes lists each scope asked for, with its title, whether it is sensitive or required, which service supplies it, whether policy allows it and why not, and a preview of what would be shared.
  • Completed, Aborted — follow status.returnTo.

Signing in

{ "spec": { "method": "EmailCode", "code": "123456" } }
{ "spec": { "method": "EmailLink", "token": "…" } }
{ "spec": { "method": "Passkey", "credential": { "id": "…", "response": { … } } } }

A wrong code is a 422 naming spec.code, with the tries left. An expired or used code or link is 410, and a link for another sign-in 403.