Another authorization for a connection that needs one: the registration held is reused when it opens, else the server registers us again.

POST

/connections/{id}/authorize

const url = 'https://api.canopyhq.dev/connections/example/authorize';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.canopyhq.dev/connections/example/authorize \
  --header 'Authorization: Bearer <token>'

Authorizations

console_token

Parameters

Path Parameters

required

string

The connection to authorize again.

Responses

202

The connection stands as authorizing; authorize is the URL the owner opens.

application/json

What a link answers: the connection as it stands, and, when the server demands an authorization, the URL the owner opens to grant it.

object

authorize

string | null

connection

required

object

auth

One of:

null
object

null

catalog

required

object

key

additional properties

A tool as advertised by its MCP server. An absent output schema stays absent.

object

description

required

string

input_schema

required

output_schema

One of:

null
unknown

null

endpoint

required

string

name

required

The tenant’s readable namespace for this connection’s tools.

string

result_limit

One of:

null
string

null

A byte count written with an optional binary unit, such as 16KiB.

string

state

Where a connection stands: linked with its catalog, or waiting on the owner to authorize it. A linked connection whose token set was refused and could not be refreshed reads as needing authorization again.

string

Allowed values: linked authorizing needs_authorization

timeout

string | null

outcome

required

The result of applying a resource write at the door.

string

Allowed values: created replaced unchanged

Example

{
  "connection": {
    "auth": {
      "kind": "bearer"
    },
    "state": "linked"
  },
  "outcome": "created"
}

401

No console token, or one that did not verify.

403

Only an owner of the tenant may configure it.

404

The tenant owns no connection by that name.

409

The connection is not one linked through an authorization.

502

The server could not be registered with; nothing changed.