---
title: "Open a brokered OAuth flow and return the provider authorize URL"
method: POST
path: "/onprem/v1/oauth/broker/sessions"
tags: ["onprem", "onprem", "__public__"]
---

# Open a brokered OAuth flow and return the provider authorize URL

`POST /onprem/v1/oauth/broker/sessions`

## Request body

- OAuthBrokerSessionCreateRequest — POST /onprem/v1/oauth/broker/sessions body (contract §2.1).
  - `provider` string, required — Provider profile name (matches the on-prem oauth profiles)
  - `scopes` string[], nullable — Optional scope override; defaults to the provider profile's default_scopes
  - `landing_url` string, nullable — Absolute https (localhost allowed) URL on the deployment to return the user to
  - `instance_hint` string, nullable — For per-tenant providers (Salesforce login/test, Showpad subdomain, Marketo REST host)

## Response `200`

Success

- SuccessResponseOAuthBrokerSessionCreateResponse
  - `success` true, required — Flag for it request was successful
  - `data` OAuthBrokerSessionCreateResponse, required — POST /onprem/v1/oauth/broker/sessions response (contract §2.1).
    - `session_id` string, required
    - `authorize_url` string, required
    - `expires_at` string, date-time, required
  - `meta` ResponseMeta
    - `requestId` string — Unique request identifier for tracing
    - `timestamp` string, date-time — Response timestamp (UTC)
    - `durationMs` integer, nullable — Request processing time in milliseconds

## Other responses

- `400` — Validation Bad Request
- `401` — Auth Invalid Token
- `403` — Forbidden Insufficient Permissions
- `404` — Resource Not Found
- `409` — Resource Conflict
- `422` — Validation Failed
- `426` — Business Quota Exceeded
- `500` — Internal Error

---

[API](https://skmtc.dev/definite/apis/defapi.md) · [All operations](https://skmtc.dev/definite/apis/defapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/definite/defapi/revisions/5ea378187147/schema)