---
title: "Oauth Authorize"
method: POST
path: "/v1/workspaces/{workspace}/oauth/authorize"
tags: ["v1", "protected", "oauth-connect"]
---

# Oauth Authorize

`POST /v1/workspaces/{workspace}/oauth/authorize`

## Request

- The document declares no server URL.
- Auth: HTTP bearer

Start a sign-in and return the provider's authorization URL to send the user to.

## Path parameters

- `workspace` string, required: Slug of the workspace the request acts in

## Request body

- OAuthAuthorizeRequest: Start a sign-in for one MCP instance or one catalog API. ``auto`` uses the operator's platform app when one serves the provider, else registers AgentArea with it (RFC 7591). ``custom`` uses an OAuth app the workspace registered with the provider, and overrides either.
  - `catalog_item_id` string, uuid, nullable: Catalog API to connect; the connection is created by this request.
  - `client_id` string, nullable
  - `client_id_secret_id` string, uuid, nullable: Existing user-owned workspace secret containing the OAuth client ID.
  - `client_secret` string, nullable
  - `client_secret_secret_id` string, uuid, nullable: Existing user-owned workspace secret containing the OAuth client secret.
  - `credential_mode` 'auto' | 'custom'
  - `instance_id` string, uuid, nullable: MCP instance to sign in to.
  - `return_to` string

## Response `200`

Successful Response

- OAuthAuthorizeResponse
  - `authorize_url` string, required
  - `connection_id` string, uuid, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-12** `e25c3ef78465`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentarea/apis/agentarea-api/changes/v1/workspaces/:workspace/oauth/authorize/post.md)

---

[API](https://skmtc.dev/agentarea/apis/agentarea-api.md) - [All operations](https://skmtc.dev/agentarea/apis/agentarea-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentarea/apis/agentarea-api/revisions/5b651833a114?raw)