# Integration routes: reconnect, refresh, resume, revoke

URL: /code/api/integration/verbs-reconnect · Id: `page:code/api/integration/verbs-reconnect`

> The Integration Verbs reconnect, refresh, resume, revoke as api.sb routes, with inputs, result, refusals and an example.

Reference for [Integration](/business/nouns/integration), one group of [Integration routes](/code/api/integration).

### Integration.reconnect
Reconnect re-approves an Integration in place, keeping its id and cursor, so nothing re-imports. [Verb page](/business/nouns/integration/reconnect?interface=api).

```text
POST /{namespace}/integrations/{integration}/reconnect
```

Path: `integration`. Emits [`Integration.reconnected`](/business/events/Integration.reconnected).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration in `needsReauth`. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `connectUrl` | `url` | Yes | The approval page; it expires in one hour. |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration, its id and cursor kept. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy/reconnect \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "connectUrl": "https://leaseline.app",
  "integration": {
    "$id": "https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy",
    "$type": "Integration",
    "acquired": "owned",
    "scope": "studio",
    "mode": "mirror",
    "state": "connecting"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Integration.reconnect",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Integration.refresh
Refresh renews an Integration’s outside token before it expires; a refused refresh moves it to `needsReauth`. [Verb page](/business/nouns/integration/refresh?interface=api).

```text
POST /{namespace}/integrations/{integration}/refresh
```

Path: `integration`. Emits [`Integration.refreshed`](/business/events/Integration.refreshed).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration to refresh. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration with a new `refreshedAt`, or in `needsReauth`. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy/refresh \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "integration": {
    "$id": "https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy",
    "$type": "Integration",
    "acquired": "owned",
    "scope": "studio",
    "mode": "mirror",
    "state": "connecting"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Integration.refresh",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Integration.resume
Resume restarts a paused Integration from its cursor and releases the Actions that waited on it. [Verb page](/business/nouns/integration/resume?interface=api).

```text
POST /{namespace}/integrations/{integration}/resume
```

Path: `integration`. Emits [`Integration.resumed`](/business/events/Integration.resumed).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | [Integration](/business/nouns/integration) | Yes | The paused Integration. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration, `connected`. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy/resume \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "integration": {
    "$id": "https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy",
    "$type": "Integration",
    "acquired": "owned",
    "scope": "studio",
    "mode": "mirror",
    "state": "connecting"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Integration.resume",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Integration.revoke
Revoke ends an Integration at once: its token is revoked with the upstream, and every record it brought in stays. [Verb page](/business/nouns/integration/revoke?interface=api).

```text
POST /{namespace}/integrations/{integration}/revoke
```

Path: `integration`. Body, as JSON: the other inputs. Emits [`Integration.revoked`](/business/events/Integration.revoked).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration to end. |
| `reason` | `text` | No | Why, kept on the Integration. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration, `revoked`. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy/revoke \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "integration": {
    "$id": "https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy",
    "$type": "Integration",
    "acquired": "owned",
    "scope": "studio",
    "mode": "mirror",
    "state": "connecting"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Integration.revoke",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```