Identity Provider

Authorization endpoint (authorization-code + PKCE)

Three ways an agent authenticates, checked in this order.

  1. API key: send Authorization: Bearer dse_... plus inbox_id= (or login_hint=<inbox email>; both may be omitted when the account has exactly one inbox). The code is minted immediately.
  2. Signed assertion: assertion= an ES256 JWS over {iss: inbox_id, sub: inbox_id, aud: "https://id.deadsimple.email", iat, exp (at most 10 minutes after iat), jti} with a kid header naming a key enrolled on the inbox. Optional client_id, redirect_uri, code_challenge and nonce claims must match the request. Each jti is accepted once.
  3. Browser: no credential at all redirects to https://app.deadsimple.email/id/consent?request_id=..., where the account owner picks an inbox and approves. Success is a 302 to redirect_uri with code and state, or, when the request sends Accept: application/json, a 200 JSON body {redirect_to, code, state}. A JSON client with no credential gets 401 login_required rather than a redirect. An unresolvable client_id or a redirect_uri that is not same-origin (open client) or not registered gets a 400 with no redirect.
get/authorize

Request

  • Base URL: https://id.deadsimple.email
  • URL: https://id.deadsimple.email/authorize
  • Auth: none required

Query parameters

client_idstring required

A registered dse_idc_ id, or (open client) an https URL sharing its origin with redirect_uri.

redirect_uristring required
response_type'code' required
scopestring

openid required. Open clients may add email and profile; registered clients may also add owner_email, org, offline_access.

code_challengestring required
code_challenge_method'S256'
statestring
noncestring
inbox_idstring

Which inbox signs in (API-key path).

login_hintstring

The inbox email address, as an alternative to inbox_id.

assertionstring

ES256 JWS signed by an enrolled key (assertion path). Also accepted as Authorization: Bearer <jws>.

Response

With Accept application/json, the redirect as data.

redirect_tostring
codestring
statestring

Changes

No recorded changes to this operation across all 1 revision of this API.