Resolve a console login code

POST

/api/certs/requests/resolve-code

curl --request POST \
  --url https://example.com/api/certs/requests/resolve-code \
  --header 'Content-Type: application/json' \
  --header 'X-Ssoossh-Key-Secret: <X-Ssoossh-Key-Secret>' \
  --data '{}'

Session-authed and CSRF-guarded. Turns the code a human read off a console screen into the request it names, and claims that request for the submitting session.

Authentication is not optional here. An unauthenticated caller must never learn whether a code is live and must never receive a request ID: the ID is the credential the certificate is delivered against.

The three failure modes are distinct on purpose, because they send the user to three different next actions: 404 no such code (retype it), 410 expired (start the login again at the machine), 403 already claimed by another session.

Authorizations

• sessionCookie

Request Body^required

The code as typed

Media typeapplication/json

One of:

object

object

object

The code as typed

object

code

required

string

Example ^generated

{}

Responses

200

Resolved and claimed

Media typeapplication/json

object

data

required

object

approval_url

required

ApprovalURL is the page to send the browser to. Returned rather than assembled client-side so the one definition of the path stays on the server, alongside the create response’s.

string

request_id

required

string

error

string

Example ^generated

{
  "data": {
    "approval_url": "example",
    "request_id": "example"
  },
  "error": "example"
}

400

Not a well-formed code

Media typeapplication/json

object

data

Data is always null on an error response.

error

required

Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.

string

error_code

required

ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.

string

Example

{
  "error": "certificate request \"9f1c…\" not found",
  "error_code": "not_found"
}

401

No valid session

Media typeapplication/json

object

data

Data is always null on an error response.

error

required

Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.

string

error_code

required

ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.

string

Example

{
  "error": "certificate request \"9f1c…\" not found",
  "error_code": "not_found"
}

403

Claimed by another user, or a cross-origin call

Media typeapplication/json

object

data

Data is always null on an error response.

error

required

Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.

string

error_code

required

ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.

string

Example

{
  "error": "certificate request \"9f1c…\" not found",
  "error_code": "not_found"
}

404

No live request carries that code

Media typeapplication/json

object

data

Data is always null on an error response.

error

required

Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.

string

error_code

required

ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.

string

Example

{
  "error": "certificate request \"9f1c…\" not found",
  "error_code": "not_found"
}

410

The request expired before the code was submitted

Media typeapplication/json

object

data

Data is always null on an error response.

error

required

Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.

string

error_code

required

ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.

string

Example

{
  "error": "certificate request \"9f1c…\" not found",
  "error_code": "not_found"
}

429

Too many code submissions

Media typeapplication/json

object

data

Data is always null on an error response.

error

required

Error is a human-readable message. Branch on the HTTP status rather than this string; it is for humans and logs.

string

error_code

required

ErrorCode is a machine-readable error classifier. One of the error_code constants from internal/apitypes; use this to decide whether to retry or branch on the failure mode.

string

Example

{
  "error": "certificate request \"9f1c…\" not found",
  "error_code": "not_found"
}