Force-refresh OAuth2 credentials for an active integration

Sidecar-only. Same response shape and same required connection_id selector as the GET endpoint; forces a refresh of every OAuth2 auth on the named connection regardless of remaining token lifetime. Called by the MITM listener's refreshOnUnauthorized hook when upstream returns 401. A caller whose credential_revision names a credential the connection no longer holds gets the current one (200, exactly as the GET) — nothing is refreshed or counted, since its 401 says nothing about the current credential. An ephemeral CONNECT run's token is refused here with 409 connect_run_no_refresh: the platform holds no stored credential for that connection yet — minting one is the reason the connect run exists — so there is nothing a refresh could produce.

POST/internal/integration-credentials/{scope}/{name}/refresh

Authorization

bearerExecToken

AuthorizationBearer <token>

Run token for container-to-host internal routes.

In: header

Path Parameters

scope*string

Package scope (e.g. @myorg)

Match^@[a-z0-9][a-z0-9-]*$

name*string

Package name

Query Parameters

connection_id*string

The connection this run bound to the integration: a member of runs.resolved_connections[<integration id>]. An id the run did not bind is a 400 connection_not_in_run.

Formatuuid

credential_revision?string

The credential_revision of the credential that was rejected. Omitted only by a caller that holds no credentials payload (a local MCP server reporting a rejected credential it received at spawn); its rejection is then counted against the connection's current credential.

Match^[0-9a-f]{16}$

curl -X POST "https://your-instance/internal/integration-credentials/string/string/refresh?connection_id=497f6eca-6276-4993-bfeb-53cbbbba6f08"

{
  "auths": [
    {
      "auth_key": "string",
      "auth_type": "string",
      "fields": {
        "property1": "string",
        "property2": "string"
      },
      "authorized_uris": [
        "string"
      ],
      "resource": "string",
      "expires_at": "2019-08-24T14:15:22Z",
      "scopes_granted": [
        "string"
      ]
    }
  ],
  "delivery_plans": {
    "property1": {
      "header_name": "string",
      "header_prefix": "string",
      "value": "string",
      "allow_server_override": true
    },
    "property2": {
      "header_name": "string",
      "header_prefix": "string",
      "value": "string",
      "allow_server_override": true
    }
  },
  "expires_at_epoch_ms": {
    "property1": 0,
    "property2": 0
  },
  "rejection_streak": 1,
  "credential_revision": "string"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "https://docs.appstrate.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing session",
  "code": "unauthorized",
  "request_id": "req_abc123"
}

{
  "type": "https://docs.appstrate.dev/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions",
  "code": "forbidden",
  "request_id": "req_abc123"
}

{
  "type": "https://docs.appstrate.dev/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Resource not found",
  "code": "not_found",
  "request_id": "req_abc123"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "https://docs.appstrate.dev/errors/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again or contact support.",
  "code": "internal_error",
  "request_id": "req_abc123"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}