# AuthorizeMcpServer authorizes credentials for one named upstream. [API catalog](/reference/api/) · [Docker Sandboxes overview](/reference/api/sandboxes/latest/) · [Product manual](https://docs.docker.com/ai/sandboxes-api/) · [OpenAPI specification](/reference/api/sandboxes/api.yaml) API version: v1 > This API is experimental. Features, interfaces, > and behavior may change. `POST /v1/mcp-servers/{mcpServer}/authorization/authorize` AuthorizeMcpServer authorizes credentials for one named upstream. Action: authorization runs an interactive grant whose result is not the request body. ## Connection and access [API connection and authentication guidance](/reference/api/sandboxes/latest/#authentication) Server: `https://connect.docker.com/sandboxes` Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement. ```json [ { "bearer": [] } ] ``` ## Example request Replace placeholders and provide the required credentials or request body. ```console curl \ --request POST \ --header "Authorization: Bearer ${TOKEN}" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data-binary @request-body \ 'https://connect.docker.com/sandboxes/v1/mcp-servers//authorization/authorize' ``` Prepare request-body using the selected media type and schema. ## Parameters ### mcpServer Location: path. Required: yes. The mcpServer id. ```json { "description": "The mcpServer id.", "in": "path", "name": "mcpServer", "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization~1authorize/post/parameters/0", "required": true, "schema": { "type": "string" } } ``` ### If-Match Location: header. Required: no. Optional current authorization etag. A supplied stale value answers 412 with failedPrecondition; omission permits create or convergence, including forced reauthorization. ```json { "description": "Optional current authorization etag. A supplied stale value answers 412 with failedPrecondition; omission permits create or convergence, including forced reauthorization.", "in": "header", "name": "If-Match", "pointer": "/paths/~1v1~1mcp-servers~1{mcpServer}~1authorization~1authorize/post/parameters/1", "schema": { "description": "(OPTIONAL) etag optionally pins the current authorization; a supplied stale value refuses.", "title": "If-Match", "type": "string" } } ``` ## Request and responses ### Request application/json Schema: ```json { "additionalProperties": false, "description": "AuthorizeMcpServerRequest starts or refreshes MCP upstream authorization.", "properties": { "forceReauth": { "description": "force_reauth starts a fresh flow while existing credentials serve until completion.\nRepeating a pending flow converges without reminting.", "type": "boolean" }, "remoteUrl": { "description": "remote_url binds authorization to a concrete upstream URL when supplied.", "format": "uri", "type": [ "string", "null" ] } }, "title": "AuthorizeMcpServerRequest", "type": "object" } ``` ### Response 200 application/json Success Schema: ```json { "allOf": [ { "$ref": "#/components/schemas/McpAuthorization" }, { "not": { "properties": { "status": { "enum": [ "pending" ] } }, "required": [ "status" ] } } ] } ``` Headers: ```json { "ETag": { "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", "schema": { "type": "string" } } } ``` ### Response 202 application/json Accepted. The resource is still progressing; read it or follow its events until completion. Schema: ```json { "allOf": [ { "$ref": "#/components/schemas/McpAuthorization" }, { "properties": { "status": { "enum": [ "pending" ] } }, "required": [ "status" ] } ] } ``` Headers: ```json { "ETag": { "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", "schema": { "type": "string" } } } ``` ### Response 412 application/json The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` etag_mismatch: ```json { "code": "failedPrecondition", "details": [ { "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", "currentEtag": "v2" } ], "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." } ``` ### Response default application/json The structured Error body identifies the failure with a stable code and optional typed details. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` Schema example: ```json { "code": "notFound", "details": [], "message": "sandbox not found" } ``` ## Complete operation contract ```json { "description": "AuthorizeMcpServer authorizes credentials for one named upstream.\nAction: authorization runs an interactive grant whose result is not the request body.", "operationId": "authorizeMcpServer", "parameters": [ { "description": "The mcpServer id.", "in": "path", "name": "mcpServer", "required": true, "schema": { "type": "string" } }, { "description": "Optional current authorization etag. A supplied stale value answers 412 with failedPrecondition; omission permits create or convergence, including forced reauthorization.", "in": "header", "name": "If-Match", "schema": { "description": "(OPTIONAL) etag optionally pins the current authorization; a supplied stale value refuses.", "title": "If-Match", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "AuthorizeMcpServerRequest starts or refreshes MCP upstream authorization.", "properties": { "forceReauth": { "description": "force_reauth starts a fresh flow while existing credentials serve until completion.\nRepeating a pending flow converges without reminting.", "type": "boolean" }, "remoteUrl": { "description": "remote_url binds authorization to a concrete upstream URL when supplied.", "format": "uri", "type": [ "string", "null" ] } }, "title": "AuthorizeMcpServerRequest", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/McpAuthorization" }, { "not": { "properties": { "status": { "enum": [ "pending" ] } }, "required": [ "status" ] } } ] } } }, "description": "Success", "headers": { "ETag": { "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/McpAuthorization" }, { "properties": { "status": { "enum": [ "pending" ] } }, "required": [ "status" ] } ] } } }, "description": "Accepted. The resource is still progressing; read it or follow its events until completion.", "headers": { "ETag": { "description": "The etag of the resource this response carries, which the next mutation of it sends as If-Match.", "schema": { "type": "string" } } } }, "412": { "content": { "application/json": { "examples": { "etag_mismatch": { "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", "value": { "code": "failedPrecondition", "details": [ { "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", "currentEtag": "v2" } ], "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The structured Error body identifies the failure with a stable code and optional typed details." } }, "security": [ { "bearer": [] } ], "summary": "AuthorizeMcpServer authorizes credentials for one named upstream.", "tags": [ "MCP gateways" ], "x-sbx-authenticated-only": false, "x-sbx-conditional-permissions": [], "x-sbx-plane": "control", "x-sbx-required-permissions": [ "mcpWrite" ], "x-sbx-resource-response": { "$ref": "#/components/schemas/McpAuthorization" }, "x-sbx-serving-surface": "management" } ``` ## Referenced schemas - [#/components/schemas/Error](/reference/api/sandboxes/latest/schemas/Error/) - [#/components/schemas/McpAuthorization](/reference/api/sandboxes/latest/schemas/McpAuthorization/)