For the complete documentation index, see llms.txt. This page is also available as Markdown.

POSTpartial

Prepare or approve a signed-in authorization request

The hosted /oauth/authorize page performs this same-origin session-authenticated protocol. Review exact scopes, Rules/disclosure and optional standing bounds before approval. A link request must be owned by an approved partner and the account must already be a party to its case.

/api/oauth/authorizereviewAccountOAuthAuthorization

Authentication and authority

Use one listed account-session, scoped OAuth, or partner credential alternative. Account tokens retain the approving account’s authority. Cookie-authenticated writes require same-origin authorization. Alternatives are OR; schemes in one alternative are AND.

CanonicalSession

The signed-in account’s session. Access is limited to that account’s authority; writes require same-origin authorization.

Parameters

This operation has no path, query, or header parameters.

Request body

Required request body.

application/json

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "const": "prepare"
        },
        "client_id": {
          "type": "string"
        },
        "redirect_uri": {
          "type": "string"
        },
        "response_type": {
          "type": "string",
          "const": "code"
        },
        "code_challenge_method": {
          "type": "string",
          "const": "S256"
        },
        "code_challenge": {
          "type": "string"
        },
        "scope": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "cases:read",
                  "fees:agentic:write",
                  "executions:report",
                  "filings:write",
                  "answers:write",
                  "submissions:write",
                  "records:confirm",
                  "records:write",
                  "invitations:write",
                  "messages:write",
                  "remedies:write",
                  "representatives:manage",
                  "procedural:request",
                  "termination:write",
                  "consents:write",
                  "offline_access"
                ]
              }
            }
          ]
        },
        "resource": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "case_id": {
          "type": "string"
        },
        "party": {
          "type": "string",
          "enum": [
            "claimant",
            "respondent"
          ],
          "description": "Require this side of the existing case; approval binds the current party membership."
        },
        "standing_offer": {
          "type": "boolean"
        }
      },
      "required": [
        "action",
        "client_id",
        "redirect_uri",
        "response_type",
        "code_challenge_method",
        "code_challenge",
        "scope",
        "resource",
        "state"
      ]
    },
    {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "const": "prepare"
        },
        "link": {
          "type": "string"
        }
      },
      "required": [
        "action",
        "link"
      ]
    },
    {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "const": "approve"
        },
        "requestId": {
          "type": "string"
        },
        "approve": {
          "type": "boolean"
        },
        "terms": {
          "$ref": "#/components/schemas/AccountOAuthTerms",
          "type": "object",
          "properties": {
            "rulesVersion": {
              "type": "string"
            },
            "rulesHash": {
              "type": "string"
            },
            "disclosureVersion": {
              "type": "string"
            },
            "disclosureHash": {
              "type": "string"
            }
          },
          "required": [
            "rulesVersion",
            "rulesHash",
            "disclosureVersion",
            "disclosureHash"
          ]
        },
        "standing": {
          "$ref": "#/components/schemas/AccountStandingBounds",
          "type": "object",
          "properties": {
            "acts": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "file_dispute",
                  "answer"
                ]
              }
            },
            "maximumAmount": {
              "type": "object",
              "properties": {
                "currency": {
                  "type": "string",
                  "const": "USD"
                },
                "minorUnits": {
                  "type": "string",
                  "pattern": "^[1-9][0-9]{0,14}$"
                }
              },
              "required": [
                "currency",
                "minorUnits"
              ]
            },
            "transactionIds": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "expiresAt": {
              "type": "string",
              "format": "date-time"
            },
            "procedure": {
              "type": "string",
              "const": "standard"
            },
            "clock": {
              "type": "string",
              "const": "ordinary"
            }
          },
          "required": [
            "acts",
            "maximumAmount",
            "expiresAt",
            "procedure",
            "clock"
          ]
        }
      },
      "required": [
        "action",
        "requestId",
        "approve",
        "terms"
      ]
    }
  ]
}

Responses

200

Successful operation.

application/json

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "request": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "clientId": {
              "type": "string"
            },
            "principalId": {
              "type": "string"
            },
            "redirectUri": {
              "type": "string"
            },
            "scope": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "cases:read",
                  "fees:agentic:write",
                  "executions:report",
                  "filings:write",
                  "answers:write",
                  "submissions:write",
                  "records:confirm",
                  "records:write",
                  "invitations:write",
                  "messages:write",
                  "remedies:write",
                  "representatives:manage",
                  "procedural:request",
                  "termination:write",
                  "consents:write",
                  "offline_access"
                ]
              }
            },
            "resource": {
              "type": "string"
            },
            "caseId": {
              "type": "string"
            },
            "terms": {
              "$ref": "#/components/schemas/AccountOAuthTerms",
              "type": "object",
              "properties": {
                "rulesVersion": {
                  "type": "string"
                },
                "rulesHash": {
                  "type": "string"
                },
                "disclosureVersion": {
                  "type": "string"
                },
                "disclosureHash": {
                  "type": "string"
                }
              },
              "required": [
                "rulesVersion",
                "rulesHash",
                "disclosureVersion",
                "disclosureHash"
              ]
            },
            "expiresAt": {
              "type": "string"
            }
          }
        },
        "client": {
          "$ref": "#/components/schemas/AccountOAuthClient",
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "kind": {
              "type": "string",
              "enum": [
                "personal",
                "agent",
                "partner"
              ]
            },
            "partnerId": {
              "type": "string"
            },
            "mcpCaseId": {
              "type": "string"
            },
            "redirectUris": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "scopes": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "cases:read",
                  "fees:agentic:write",
                  "executions:report",
                  "filings:write",
                  "answers:write",
                  "submissions:write",
                  "records:confirm",
                  "records:write",
                  "invitations:write",
                  "messages:write",
                  "remedies:write",
                  "representatives:manage",
                  "procedural:request",
                  "termination:write",
                  "consents:write",
                  "offline_access"
                ]
              }
            },
            "createdAt": {
              "type": "string"
            },
            "revokedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "name",
            "kind",
            "redirectUris",
            "scopes",
            "createdAt"
          ]
        }
      },
      "required": [
        "request",
        "client"
      ]
    },
    {
      "type": "object",
      "properties": {
        "redirect": {
          "type": "string"
        },
        "grant": {
          "$ref": "#/components/schemas/AccountAuthorityGrant",
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "principalId": {
              "type": "string"
            },
            "clientId": {
              "type": "string"
            },
            "delegatePartnerId": {
              "type": "string"
            },
            "scope": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "cases:read",
                  "fees:agentic:write",
                  "executions:report",
                  "filings:write",
                  "answers:write",
                  "submissions:write",
                  "records:confirm",
                  "records:write",
                  "invitations:write",
                  "messages:write",
                  "remedies:write",
                  "representatives:manage",
                  "procedural:request",
                  "termination:write",
                  "consents:write",
                  "offline_access"
                ]
              }
            },
            "resource": {
              "type": "string"
            },
            "terms": {
              "$ref": "#/components/schemas/AccountOAuthTerms",
              "type": "object",
              "properties": {
                "rulesVersion": {
                  "type": "string"
                },
                "rulesHash": {
                  "type": "string"
                },
                "disclosureVersion": {
                  "type": "string"
                },
                "disclosureHash": {
                  "type": "string"
                }
              },
              "required": [
                "rulesVersion",
                "rulesHash",
                "disclosureVersion",
                "disclosureHash"
              ]
            },
            "caseId": {
              "type": "string"
            },
            "caseBinding": {
              "type": "object",
              "properties": {
                "disputeId": {
                  "type": "string"
                },
                "membershipId": {
                  "type": "string"
                },
                "side": {
                  "type": "string",
                  "enum": [
                    "claimant",
                    "respondent"
                  ]
                }
              },
              "required": [
                "disputeId",
                "membershipId",
                "side"
              ]
            },
            "standing": {
              "$ref": "#/components/schemas/AccountStandingBounds",
              "type": "object",
              "properties": {
                "acts": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "file_dispute",
                      "answer"
                    ]
                  }
                },
                "maximumAmount": {
                  "type": "object",
                  "properties": {
                    "currency": {
                      "type": "string",
                      "const": "USD"
                    },
                    "minorUnits": {
                      "type": "string",
                      "pattern": "^[1-9][0-9]{0,14}$"
                    }
                  },
                  "required": [
                    "currency",
                    "minorUnits"
                  ]
                },
                "transactionIds": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "expiresAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "procedure": {
                  "type": "string",
                  "const": "standard"
                },
                "clock": {
                  "type": "string",
                  "const": "ordinary"
                }
              },
              "required": [
                "acts",
                "maximumAmount",
                "expiresAt",
                "procedure",
                "clock"
              ]
            },
            "approvedAt": {
              "type": "string"
            },
            "expiresAt": {
              "type": "string"
            },
            "revokedAt": {
              "type": "string"
            },
            "source": {
              "type": "string",
              "enum": [
                "authorization_code",
                "hosted_link",
                "agent_registration",
                "connector"
              ]
            },
            "termsChange": {
              "type": "string",
              "enum": [
                "hold_writes"
              ],
              "description": "Set on a connector grant approved through a consent screen that states the hold. A later Rules or disclosure change holds the grant, allowing only cases:read, until the person re-accepts."
            },
            "termsHistory": {
              "type": "array",
              "description": "Terms this grant carried before each re-acceptance, oldest first.",
              "items": {
                "type": "object",
                "properties": {
                  "terms": {
                    "$ref": "#/components/schemas/AccountOAuthTerms",
                    "type": "object",
                    "properties": {
                      "rulesVersion": {
                        "type": "string"
                      },
                      "rulesHash": {
                        "type": "string"
                      },
                      "disclosureVersion": {
                        "type": "string"
                      },
                      "disclosureHash": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "rulesVersion",
                      "rulesHash",
                      "disclosureVersion",
                      "disclosureHash"
                    ]
                  },
                  "acceptedAt": {
                    "type": "string"
                  },
                  "supersededAt": {
                    "type": "string"
                  },
                  "via": {
                    "type": "string",
                    "enum": [
                      "consent_screen",
                      "account_reacceptance"
                    ]
                  }
                },
                "required": [
                  "terms",
                  "acceptedAt",
                  "supersededAt",
                  "via"
                ]
              }
            },
            "reacceptance": {
              "type": "object",
              "description": "The latest re-acceptance of the current terms from the person's account.",
              "properties": {
                "at": {
                  "type": "string"
                },
                "sessionId": {
                  "type": "string"
                },
                "statementSha256": {
                  "type": "string"
                }
              },
              "required": [
                "at",
                "sessionId",
                "statementSha256"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "expired",
                "revoked",
                "reacceptance_required",
                "held"
              ]
            }
          },
          "required": [
            "id",
            "principalId",
            "clientId",
            "scope",
            "resource",
            "terms",
            "approvedAt",
            "expiresAt",
            "source"
          ]
        }
      },
      "required": [
        "redirect"
      ]
    }
  ]
}
default

Authorization failure; consent_required requires explicit reacceptance.

application/json

{
  "$ref": "#/components/schemas/AccountOAuthError",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "error_description": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ]
}

Example response

Successful response

{
  "request": {},
  "client": {
    "id": "id_test",
    "name": "Maya Chen",
    "kind": "personal",
    "redirectUris": [
      "redirectUris_test"
    ],
    "scopes": [
      "cases:read"
    ],
    "createdAt": "createdAt_test"
  }
}

Errors

Read the response status and stable error code. See errors and rate limits for recovery. Refresh the resource before resolving a state or digest conflict.

Idempotency and retries

  • For throttling, honor Retry-After when present. Back off on retryable server failures.
  • The request is accepted only when its credential, authority, case state, and resource preconditions are satisfied.