Skip to content
Sudomimus

Establish a new authentication inquiry for an application.

POST
/establish
curl --request POST \
  --url https://connect-api.sudomimus.com/establish \
  --header 'Content-Type: application/json' \
  --data '{ "applicationAnchor": "example", "authenticationConstraints": [ { "accessTokenTtlSeconds": 1, "refreshTokenTtlSeconds": 1, "method": "PASSKEY_USERNAMELESS", "payload": {} } ], "realizeConstraints": [ { "accessTokenTtlSeconds": 1, "refreshTokenTtlSeconds": 1, "constraintType": "EMAIL", "payload": { "allowedEmails": [ "example" ] } } ], "returnMethods": [ { "type": "CALLBACK", "payload": { "callbackUrl": "example" } } ] }'

Creates an authentication inquiry for the calling application. The client-auth JWT binds the exact request bytes and is single-use; see SudomimusClientJWT for its claim contract.

Constraint and return-method arrays are optional. When supplied, they narrow the application’s configured rules and MUST be non-empty. The schemas define per-field limits; the three arrays together are limited to 65,536 serialized UTF-8 bytes.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
applicationAnchor
required

Public anchor identifying the integrating application.

string
authenticationConstraints

Optional per-inquiry narrowing of the application’s authentication-rule layer. Absent means no narrowing. If present, the array MUST be non-empty; empty arrays are rejected with 400.

Array
>= 1 items <= 16 items
One of: discriminator: method
object
accessTokenTtlSeconds

Per-constraint override for access token lifetime. Resolved at realize time.

integer
>= 60 <= 604800
refreshTokenTtlSeconds

Per-constraint override for refresh token lifetime. Resolved at realize time.

integer
>= 86400 <= 31536000
method
required
string
Allowed values: PASSKEY_USERNAMELESS
payload
required

Empty payload — narrows to usernameless (discoverable-credential) passkey login shown before an email is entered. Other configured authorization rules still apply.

object
realizeConstraints

Optional per-inquiry narrowing of the application’s realize-rule layer. Absent means no narrowing. If present, the array MUST be non-empty; empty arrays are rejected with 400.

Array
>= 1 items <= 16 items
One of: discriminator: constraintType
object
accessTokenTtlSeconds

Per-constraint override for access token lifetime. Resolved at realize time.

integer
>= 60 <= 604800
refreshTokenTtlSeconds

Per-constraint override for refresh token lifetime. Resolved at realize time.

integer
>= 86400 <= 31536000
constraintType
required
string
Allowed values: EMAIL
payload
required
object
allowedEmails
required

List of email addresses or glob patterns the realized identity must match.

Array<string>
>= 1 items <= 128 items unique items
returnMethods

Optional return methods for this inquiry. Connect accepts CALLBACK, STATUS_POLL, and REVEAL. CALLBACK includes its concrete delivery URL. Absence means no per-inquiry narrowing, but CALLBACK is not available without a URL. If supplied, the array MUST be non-empty.

Array
>= 1 items <= 3 items
One of: discriminator: type
object
type
required
string
Allowed values: CALLBACK
payload
required
object
callbackUrl
required

Concrete callback URL for this inquiry. The host MUST match one of the application’s allowed callback domains. The scheme MUST be HTTPS except loopback HTTP for local development (localhost, 127.0.0.1, [::1]). After realization, Connect appends the canonical exposure-key and confirmation-key query parameters. Existing query parameters and fragments are preserved; caller-supplied or duplicate values for the two canonical names are overwritten. The URL MUST be concrete and MUST NOT contain Inquiry-key templates. Length is measured in UTF-8 bytes.

string
<= 2048 characters

Responses

Section titled “Responses”

200

Section titled “200”

Inquiry established.

Media typeapplication/json
object
applicationAnchor
required
string
exposureKey
required

Public half of the inquiry key pair; safe to share with the user agent.

string
hiddenKey
required

Private half of the inquiry key pair; must stay on the originating client.

string
Examplegenerated
{
  "applicationAnchor": "example",
  "exposureKey": "example",
  "hiddenKey": "example"
}

Headers

Section titled “Headers”
Cache-Control
string
Allowed values: no-store

Prevent storage of the credential-bearing response.

Pragma
string
Allowed values: no-cache

Legacy cache instruction retained for credential responses.

401

Section titled “401”

Client-auth JWT missing, malformed, expired, or invalid.

Media typeapplication/json

Error response body. Known failures may include a stable reason. Some failures are status-only and have an empty body. A missing, malformed, or structurally invalid JSON body returns InvalidBody.

object
reason

Stable machine-readable reason code.

string
Examplegenerated
{
  "reason": "example"
}

403

Section titled “403”

Application is not ACTIVE, or its parent Sector or Organization is unavailable. Reason ApplicationNotActive.

Media typeapplication/json

Error response body. Known failures may include a stable reason. Some failures are status-only and have an empty body. A missing, malformed, or structurally invalid JSON body returns InvalidBody.

object
reason

Stable machine-readable reason code.

string
Examplegenerated
{
  "reason": "example"
}

default

Section titled “default”

Error response.

Media typeapplication/json

Error response body. Known failures may include a stable reason. Some failures are status-only and have an empty body. A missing, malformed, or structurally invalid JSON body returns InvalidBody.

object
reason

Stable machine-readable reason code.

string
Examplegenerated
{
  "reason": "example"
}