# Connected apps

## Summary

A connected app is an AI agent, such as Claude Code or Codex, that you have
allowed to work in Talewright for you. You do not create a key and paste it
into a file. The app sends your browser to Talewright, you sign in, choose the
organization, the workspaces and the permissions, and press "Allow". The app
then receives tokens of its own and talks to Talewright's MCP server.

A connected app is a credential, like an API key. It acts for you, only in the
workspaces and with the scopes you chose, and never with more rights than you
have at that moment. You can see every connected app and disconnect it at any
time. Each time you allow an app, that is a connection of its own: the same
app on a second computer is a second connection, and neither ends the other.
The rules both kinds share are in
[Credentials and scopes](credentials.md).

The connection uses the standard OAuth authorization code flow with PKCE.

## Who can do what

| Action | Owner | Admin | Member | Signed-in person | Credential | Scope a credential needs |
| --- | --- | --- | --- | --- | --- | --- |
| Allow or deny an app's request to connect | Yes | Yes | Yes | Yes | No | Browser only |
| Grant an app `files:approve` | Yes | Yes | No | | No | Browser only |
| List your connected apps | Yes | Yes | Yes | Yes | No | Browser only |
| Disconnect one of your connected apps | Yes | Yes | Yes | Yes | No | Browser only |
| Read the activity of your connected app | Yes | Yes | Yes | Yes | No | Browser only |
| List every member's connected apps (Key management) | Yes | Yes | No | | No | Browser only |
| Revoke any member's connected app | Yes | Yes | No | | No | Browser only |
| Call MCP tools as the connected app | | | | | Yes | The scopes granted at consent |
| Revoke its own tokens (the app itself) | | | | | Yes | None: it presents its token |

- "Owner or admin" for `files:approve` means owner or admin in every workspace
  the app is given.
- Someone with an account but no workspace can deny a request, not allow one.

## How it works

### Which apps can connect

- An app identifies itself by a client ID that is a web address. At that
  address the app publishes a small document that describes it: its name and
  the addresses it may return to.
- Talewright accepts apps whose client ID starts with
  `https://claude.ai/oauth/` (Claude, including Claude Code) or
  `https://chatgpt.com/oauth/codex/` (Codex).
- Any other app is refused before anyone is asked: "Talewright does not accept
  this app yet."
- Apps do not register with Talewright in advance. There is no registration
  endpoint.
- Apps have no secret. An app that sends one is refused.
- Any other MCP client can still connect with an API key. See
  [MCP](mcp.md#authentication).

### The connection, step by step

1. The app calls the MCP endpoint without a token. Talewright answers `401`
   and says where to find out how to sign in.
2. The app reads two discovery documents, then opens your browser at
   Talewright's authorization address with what it asks for.
3. Talewright checks the app and the address it wants to return to. If either
   is wrong, your browser shows "This app cannot connect" and nothing is sent
   to the app.
4. Your browser lands on the consent screen, `/connect?request=<id>`. If you
   are signed out, you sign in (or create an account) first and come back to
   the same request. The first signed-in account that opens the request
   becomes the only one that can answer it.
5. You choose the organization, the workspaces, the permissions and the
   lifetime, and press "Allow" or "Deny".
6. Your browser returns to the app with a one-time code (or with
   `access_denied`).
7. The app exchanges the code for an access token and a refresh token. At
   this moment the connected app is created, it appears under **Settings >
   Connected apps**, and you get a security email.
8. The app calls MCP tools with the access token and renews it with the
   refresh token.

### The request to connect

- A request stays open for 10 minutes.
- A request is answered once. After "Allow" or "Deny" it cannot be opened
  again.
- A request belongs to the first signed-in person who opens it. The app does
  not choose who.
- From then on the request does not exist for anyone else. Another account
  that opens the same address sees "This request has ended"; through the API
  it gets `404 NOT_FOUND`, the same answer as for an unknown request ID, for
  reading and for deciding. Nothing about the request changes.
- Why: the address of the consent screen can leak, for example from a shared
  screen or a pasted link. Whoever holds it must not be able to connect the
  app to their own account in your place, or answer for you.
- Answering a request that nobody has opened yet makes it the answerer's in
  the same step.
- A refused decision does not: the request is left as it was.
- There is no way to hand a request to another account. Signed in to the
  wrong account? Start again from the app.
- The app asks for scopes. You can grant fewer, never more: a scope the app
  did not ask for is not offered and cannot be granted.
- An app that asks for no scopes is treated as asking for `workspace:read`,
  `files:read` and `files:write`. It is never treated as asking for
  `files:approve`.
- You choose one organization and 1 to 20 of its workspaces that you reach.
- You choose how long the connection lasts: 30, 90, 180 or 365 days. The
  default is 90 days.
- Every scope the app asked for is ticked, except `files:approve`.
- `files:approve` ("Set file statuses") is always a separate, unticked choice.
  It can be ticked only by someone who is owner or admin in every chosen
  workspace. Changing the organization or the workspaces unticks it again.
- Granting `files:approve` as a member answers `403 FORBIDDEN`.
- A refused decision (for example a workspace you do not reach) leaves the
  request open, so you can correct it and decide again within the 10 minutes.

### The code and the tokens

- The code the app gets back works for 60 seconds and for one attempt. The
  first attempt uses it up, whether it succeeds or not.
- If a used code is presented again, the connected app it created is revoked
  at once. This protects you if the code was intercepted.
- When the code is exchanged, Talewright checks again that you still reach
  the workspaces you chose and, for `files:approve`, that you are still owner
  or admin in each. If not, the exchange is refused and no app is connected.
- Resetting or changing your password, deleting your account, or leaving or
  being removed from the organization also ends codes not yet exchanged and
  requests you opened, so they no longer connect anything. An exchange already
  running when that happens finishes first, and its app is disconnected with
  the rest.
- The **access token** starts with `at1_` and works for 60 minutes.
- The **refresh token** starts with `rt1_`. It stops working after 30 days
  without a refresh.
- Each refresh gives a new access token and a new refresh token. The old
  refresh token is used up.
- If a used refresh token is presented again, the connected app is revoked at
  once.
- Neither token outlives the connected app. When the app's lifetime (30 to 365
  days) ends, the app must ask you again.
- A refresh cannot change the scopes. It cannot narrow them and it cannot add
  `files:approve`.
- Token answers are never cached (`Cache-Control: no-store`).

### Where the tokens work

- An access token works at the MCP endpoint, `/mcp`, and nowhere else.
- At the REST API, `/v1`, an access token answers `401 UNAUTHENTICATED` with
  reason `INVALID_TOKEN`. To call REST, use an API key.
- A refresh token works only at the token endpoint. Sent as a bearer token
  anywhere, it answers `401`.
- A token works only for the app it was issued to.

### Several connections per app

- Every "Allow" makes a connection of its own, with its own tokens and its
  own workspaces, scopes and lifetime.
- Connecting the same app again for the same organization, for example Claude
  Code on a second computer, adds a second connection. It never ends or
  changes an earlier one.
- Each connection is refreshed, disconnected and revoked on its own. Ending
  one leaves the others working.
- The rules for tokens hold per connection: a used refresh token presented
  again revokes that connection only.
- Connecting the same app for a second organization also makes a separate
  connection.
- You can hold at most 10 working connections to one app in one organization.
  Revoked and expired connections do not count. At the limit, "Allow" answers
  `409 CONFLICT`, `details.reason` `CONNECTION_LIMIT`, and the consent screen
  says "You already have 10 connections to this app in this organization.
  Disconnect one under Settings, Connected apps, then allow again." The
  request stays open for its 10 minutes.
- The app sends no name for the computer or the installation it runs on, and
  Talewright does not fingerprint devices. Two connections of one app are told
  apart by when each was connected, when it was last used, and the MCP client
  that last used it.

### What a connected app can do

- Exactly what its scopes allow, in its workspaces and in its organization
  folder, as you. The scopes are the same four as for API keys:
  `workspace:read`, `files:read`, `files:write` and `files:approve`.
- Its MCP tool list shows only the tools its scopes allow.
- It cannot do what no credential can do: make files public, delete for good,
  apply a library proposal, manage credentials, members, organizations or
  workspaces.
- Everything it changes is recorded with its ID and is visible as its
  activity.
- See [Credentials and scopes](credentials.md#scopes) and
  [Roles and permissions](../reference/permissions.md).

### Listing

- **Settings > Connected apps** lists your connections that are not revoked,
  newest first. The same app connected twice is two rows.
- Each shows the app's name, the host that identifies it, when it was
  connected ("Connected" with date and time), and the MCP client that last
  connected with it (name, version and MCP protocol version).
- Each shows its organization, its workspaces, its scopes, when it expires and
  when it was last used.
- Owners and admins see every member's connected apps under "Key management",
  together with API keys, one row per connection with the same "Connected"
  date and time.
- A connection that expired stays in both lists for 30 days, marked "Expired",
  then leaves them.

### Disconnecting

- Disconnecting stops the access token and the refresh token at once. The next
  MCP call answers `401`, and the refresh token no longer exchanges.
- It cannot be undone. The app must ask you again to reconnect.
- What the app did stays: files it uploaded, changes it made, and
  organization folder proposals it prepared, which stay for review.
- A connection ends in any of these ways:
  - You press "Disconnect".
  - An owner or admin revokes it in Key management.
  - The app revokes its own token.
  - You leave the organization or are removed from it.
  - You reset or change your password, or delete your account.
  - A used code or refresh token is presented again.
  - The connection's lifetime ends.

### Rate limits

- The OAuth endpoints (`/oauth/authorize`, `/oauth/token`, `/oauth/revoke`)
  together allow 100 requests per client address in 15 minutes. Past that they
  answer `429 RATE_LIMITED` with `Retry-After`.
- MCP requests of a connected app count against the same limits as API keys:
  600 a minute per connection, 3,000 a minute per organization.

## In the app

### Connect Claude Code

**Settings > Connected apps** shows the section "Connect Claude Code". The
command palette opens it with "Connect Claude Code or another agent".

1. "In a terminal, add Talewright to Claude Code:"

   ```sh
   claude mcp add --transport http talewright https://app.usetalewright.com/mcp
   ```

   "Copy command" copies it.
2. "Sign in: run `claude mcp login talewright`, or run `/mcp` in Claude Code
   and choose `talewright`. Your browser opens Talewright, where you choose the
   workspaces and permissions. The app then shows here."

`claude mcp add` stores the server for the current project only, unless you
add `--scope user`.

The link "Agent guide for Codex, Cursor and other apps" opens the agent guide
at `/agent-guide.md`.

### Connect Codex

1. Add this to `~/.codex/config.toml`:

   ```toml
   [mcp_servers.talewright]
   url = "https://app.usetalewright.com/mcp"
   ```

2. Run `codex mcp login talewright` and approve the workspaces and scopes in
   the browser.

### The consent screen

The screen is titled "Connect {app}". It says "{app}, identified by {host},
asks to act as {your email} through Talewright's MCP server." and "Setting
file statuses requires the separate permission you select below."

| Field | What it does |
| --- | --- |
| "Organization" | The organization the app works in. One is preselected. |
| "Workspaces" | "The app reaches these and the organization folder, and only while you do." If you reach only one workspace of the organization, it is ticked. |
| "Permissions" | "The app asked for every permission below. Setting file statuses starts unticked: tick it only if the app needs it. Untick anything else it does not need. Write includes read." Only the scopes the app asked for are shown. |
| "Expires" | "In 30 days", "In 90 days" (preselected), "In 180 days" or "In 365 days". |

Below the fields: "After you decide, you return to {host}." Then "Allow" and
"Deny".

Other screens you can meet:

| Screen | When |
| --- | --- |
| "Connect an app" - "Sign in to choose what the app may do for you. You come back here afterwards." with "Sign in" and "Create account" | You are signed out. |
| "You have no workspace yet" - "An app reaches workspaces. Join or create an organization, then start again from the app." with only "Deny" | Your account reaches no workspace. |
| "This app cannot connect" - a reason, then "Nothing was shared with it." | The app or its return address was refused. |
| "This request has ended" - "Requests last 10 minutes, are answered once and stay with the account that opened them first. Start again from the app." | The request is older than 10 minutes, already answered, unknown, or was first opened by another account. |
| "Could not open the request" - "Something went wrong. Try again." | The request could not be read. |

Messages under the fields: "Choose an organization you belong to.", "Choose 1
to 20 workspaces.", "Choose at least one permission." and "Choose 30, 90, 180
or 365 days."

### The list of connected apps

The table "Connected apps" has the columns "App", "Access" and "Expires". With
none it says "No connected apps yet."

- "Activity" opens what was done with the app.
- Each row is one connection. Under the app's name and host it says
  "Connected {date and time}".
- "Disconnect" asks first: "Disconnect {name}?" - "The connection made {date
  and time} stops working at once and must ask you again to reconnect. Other
  connections to {name} keep working. Work it prepared stays for review."
  Confirm with "Disconnect", or "Cancel" to keep it.
- "Disconnected {name}" confirms.

### Key management (owners and admins)

Connected apps of every member are listed in the table "Credentials" as
"Connected app from {host}" with "Connected {date and time}", one row per
connection. "Revoke" ends that one connection and asks first: "{member}'s connected app
stops working at once. They can connect it again if they still need it."

## For agents

This section is for people who build an MCP client. A person using Claude
Code or Codex needs none of it.

### Endpoints

All are on the app's host, `https://app.usetalewright.com`.

| Endpoint | Purpose |
| --- | --- |
| `GET /.well-known/oauth-protected-resource/mcp` | Describes the MCP endpoint as a protected resource. |
| `GET /.well-known/oauth-authorization-server` | Describes the authorization server. |
| `GET /oauth/authorize` | Starts a request to connect. Opened in the person's browser. |
| `POST /oauth/token` | Exchanges a code, or refreshes tokens. |
| `POST /oauth/revoke` | Revokes a token and with it the connection. |

- These endpoints take no session. Cookies are ignored.
- They are not part of `/v1` and not in the OpenAPI document.
- The two discovery documents may be cached for 5 minutes.

### Discovery

The protected resource document names the `resource` (the MCP endpoint's URL),
the `authorization_servers`, the `scopes_supported` (the four scopes) and
`bearer_methods_supported` (`header`).

The authorization server document states:

| Property | Value |
| --- | --- |
| `authorization_endpoint`, `token_endpoint`, `revocation_endpoint` | The three `/oauth/` addresses |
| `response_types_supported` | `code` |
| `response_modes_supported` | `query` |
| `grant_types_supported` | `authorization_code`, `refresh_token` |
| `code_challenge_methods_supported` | `S256` |
| `token_endpoint_auth_methods_supported` | `none` |
| `scopes_supported` | `workspace:read`, `files:read`, `files:write`, `files:approve` |
| `client_id_metadata_document_supported` | `true` |
| `authorization_response_iss_parameter_supported` | `true` |

There is no registration endpoint and no OpenID Connect configuration.

### The client metadata document

The document at the client ID's address must:

- be served over `https`, with status `200`, as `application/json`, without a
  redirect, within 5 seconds and in at most 16 KiB;
- have a `client_id` equal to its own address;
- list 1 to 20 `redirect_uris`;
- have no `client_secret`, and a `token_endpoint_auth_method` that is absent
  or `none`.

`client_name` is the name people see, cut to 100 characters. Without one, the
address's host is shown. The document is read again at every request to
connect.

A `redirect_uri` must be `https`, or `http` on a loopback host (`127.0.0.1`,
`[::1]` or `localhost`). It must match a listed address exactly, except that a
loopback address may use any port. It must have no fragment.

### The authorization request

`GET /oauth/authorize` takes these query parameters, each at most once
(`resource` may repeat with the same value):

| Parameter | Required | Value |
| --- | --- | --- |
| `client_id` | Yes | The client ID address. |
| `redirect_uri` | Yes | One of the document's addresses. |
| `response_type` | Yes | `code` |
| `code_challenge` | Yes | The PKCE challenge: 43 base64url characters. |
| `code_challenge_method` | Yes | `S256` |
| `resource` | Yes | The MCP endpoint's URL, exactly as the discovery document gives it. |
| `scope` | No | Space-separated scopes. Without it: `workspace:read files:read files:write`. |
| `state` | No | Up to 500 characters. Returned unchanged. |

The answer is a redirect (`302`): to the consent screen, to the app's own
`redirect_uri` with an `error`, or to the "This app cannot connect" screen.
Every redirect back to the app carries `iss` and, when given, `state`.

### The token request

`POST /oauth/token` takes a form body (`application/x-www-form-urlencoded`, at
most 16 KiB, each field once, no `Authorization` header, no `client_secret`).

Exchanging a code:

| Field | Value |
| --- | --- |
| `grant_type` | `authorization_code` |
| `client_id` | The client ID address. |
| `code` | The code from the redirect. |
| `redirect_uri` | The same address as in the authorization request. |
| `code_verifier` | The PKCE verifier: 43 to 128 unreserved characters. |
| `resource` | The MCP endpoint's URL. Required. |

Refreshing:

| Field | Value |
| --- | --- |
| `grant_type` | `refresh_token` |
| `client_id` | The client ID address. |
| `refresh_token` | The current refresh token. |
| `resource` | Optional. If sent, the MCP endpoint's URL. |
| `scope` | Optional. If sent, exactly the scopes the connection holds. |

The answer:

```json
{
  "access_token": "at1_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt1_...",
  "scope": "workspace:read files:read files:write"
}
```

### Revoking

`POST /oauth/revoke` takes `token` and `client_id` as form fields. A token of
that app, access or refresh, revokes its connection. Any other token changes
nothing. The answer is `200` in both cases.

### Reading the connection from inside

The MCP tool `credential_read` tells a connected app what it is:

```json
{
  "id": "0192f0a1-6f2e-7c11-9a55-2f6d0c1e7b90",
  "kind": "connected_app",
  "name": "Claude Code",
  "user": { "id": "0192e7c4-0a10-7d55-8e21-4c9b7a6d5e30", "fullName": "Ada Example" },
  "organization": { "id": "0192e7c4-0b22-7e61-9f32-5dab8b7e6f41", "name": "Keystone" },
  "workspaces": [
    { "id": "0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21", "name": "Keystone Main" }
  ],
  "scopes": ["workspace:read", "files:write"],
  "expiresAt": "2027-02-12T09:12:44Z",
  "client": {
    "clientID": "https://claude.ai/oauth/claude-code-client-metadata",
    "name": "Claude Code"
  }
}
```

### Session operations behind the consent screen

| Operation | Capability | Access |
| --- | --- | --- |
| `GET /v1/oauth/requests/{requestID}` | `credential.oauth_requests.get` | Browser only |
| `POST /v1/oauth/requests/{requestID}/decision` | `credential.oauth_requests.decide` | Browser only |
| `GET /v1/me/connected-apps` | `credential.connected_apps.list` | Browser only |
| `DELETE /v1/me/connected-apps/{credentialID}` | `credential.connected_apps.disconnect` | Browser only |

The decision body is `allow` (required), and when allowing `organizationID`,
`workspaceIDs`, `scopes` and optionally `expiresInDays`. The answer is
`{ "redirectURL": "..." }`: where the browser goes next.

The first account to read a request owns it. For every other account both
operations answer `404 NOT_FOUND`, exactly as for an unknown `requestID`. A
decision on a request nobody has read makes the decider its owner; a decision
that is refused (`403`, `422`) changes nothing.

## Edge cases

- **You press "Allow" twice, or open the request in two tabs.** The first
  decision counts. The second finds no open request: "This request has ended".
- **You take longer than 10 minutes.** "This request has ended". Start again
  from the app.
- **Someone else opens the consent address after you.** They see "This
  request has ended". Your screen keeps working and your decision counts.
- **Someone else opens the consent address before you.** The request is
  theirs. You see "This request has ended". Start again from the app, and
  disconnect anything that person connected if it shows up in Key management.
- **You opened the request signed in to the wrong account.** The request stays
  with that account. Signing in to the right one does not move it. Start
  again from the app.
- **The app takes longer than 60 seconds to exchange the code.** The exchange
  is refused. Nothing is connected. Start again from the app.
- **The exchange fails for any reason.** The code is used up anyway. Start
  again from the app.
- **You are removed from a chosen workspace between "Allow" and the
  exchange.** The exchange is refused and nothing is connected.
- **You untick everything the app asked for.** "Choose at least one
  permission." An app cannot be connected with no scope.
- **The app asked for `files:approve` and you are a member.** The choice is
  greyed out, marked "(owner or admin only)". You can still allow the other
  scopes.
- **The app did not ask for `files:approve`.** It is not offered, and cannot
  be granted, whoever you are.
- **You connect Claude Code on two computers for the same organization.** Two
  connections. Both keep working, each with its own tokens, and each is
  listed with the time it was connected.
- **You connect the same app an eleventh time for one organization.** "Allow"
  is refused with `CONNECTION_LIMIT` until you disconnect one. Expired and
  disconnected connections do not count.
- **You allowed a request just before reaching the limit and the app exchanges
  its code after.** The exchange answers `invalid_grant` and nothing is
  connected.
- **You connect the same app in two organizations.** Two separate
  connections.
- **The access token is sent to the REST API.** `401 INVALID_TOKEN`. This is
  expected: connected apps work through MCP.
- **The refresh token is sent as a bearer token.** `401`.
- **An app sends a `client_secret`.** `invalid_client`.
- **A refresh asks for fewer scopes.** `invalid_scope`. The refresh token is
  not used up and can be tried again without `scope`.
- **A refresh asks to add `files:approve`.** `invalid_scope`.
- **Another app presents your app's refresh token.** `invalid_grant`. Your
  connection is not affected.
- **Another app tries to revoke your app's token.** `200`, and nothing
  changes.
- **An MCP session is open when you disconnect.** Its next tool call fails
  with `401`.
- **You are demoted from admin to member while an app holds
  `files:approve`.** The app keeps the scope but its status changes are
  refused with `403 FORBIDDEN`.
- **A request to `/mcp` carries an `Origin` header, as a web page calling it
  from a browser would.** Refused with `403`. See [MCP](mcp.md#transport).
- **A loopback redirect on another port than listed.** Accepted. Command-line
  apps pick a free port each time.
- **Your account has no workspace.** You can only deny. Join or create an
  organization, then start again from the app.

## Errors

The OAuth endpoints answer with OAuth errors. The full list, with every
description, is in [Errors](../reference/errors.md#oauth-errors).

| Where | Error | Meaning | What to do |
| --- | --- | --- | --- |
| "This app cannot connect" | `unauthorized_client` | Talewright does not accept this app. | Use an accepted app, or an API key. |
| "This app cannot connect" | `invalid_client` | The app's document could not be read or is not valid. | The app's developer must fix it. |
| "This app cannot connect" | `invalid_redirect_uri` | The return address is not listed by the app. | The app's developer must fix it. |
| "This app cannot connect" | `invalid_request` | The request has no `client_id`. | The app's developer must fix it. |
| Back at the app | `access_denied` | You pressed "Deny". | Nothing. |
| Back at the app | `invalid_request`, `unsupported_response_type`, `invalid_target`, `invalid_scope` | The app's request is malformed. | The app's developer must fix it. |
| Token endpoint | `invalid_grant` (400) | The code or refresh token is unknown, used, expired or another app's, or you no longer reach what you granted. | Start again from the app. |
| Token endpoint | `invalid_client` (401) | No `client_id`, or a secret was sent. | The app's developer must fix it. |
| Token endpoint | `invalid_scope`, `invalid_target`, `invalid_request`, `unsupported_grant_type` (400) | The token request is malformed. | The app's developer must fix it. |
| Any `/oauth/` endpoint | `RATE_LIMITED` (429) | More than 100 requests from one address in 15 minutes. | Wait for `Retry-After`. |
| Consent | `NOT_FOUND` (404) | The request is unknown, answered, older than 10 minutes, or was first opened by another account. | Start again from the app. |
| Consent | `FORBIDDEN` (403) | A member tried to grant `files:approve`, or a bearer token called a consent operation (`SESSION_REQUIRED`). | Untick it, or use a browser. |
| Consent | `VALIDATION_FAILED` (422) | `organizationID`, `workspaceIDs`, `scopes` (including one the app did not ask for) or `expiresInDays`. | Correct the field and decide again. |
| Consent | `CONFLICT` (409), reason `CONNECTION_LIMIT` | You already have 10 working connections to this app in this organization. | Disconnect one, then allow again. |
| MCP | `UNAUTHENTICATED` (401) | The access token expired, or the app was disconnected. | The app refreshes, or asks you again. |

## Limits

| Limit | Value |
| --- | --- |
| Time to answer a request | 10 minutes |
| Code lifetime | 60 seconds, one attempt |
| Access token lifetime | 60 minutes |
| Refresh token lifetime | 30 days without a refresh |
| Connection lifetime | 30, 90 (default), 180 or 365 days |
| Workspaces per connection | 1 to 20 |
| Working connections per member, app and organization | 10 |
| `state` | Up to 500 characters |
| App name shown | Up to 100 characters |
| App document | Up to 16 KiB, read within 5 seconds, 1 to 20 return addresses |
| Token request body | Up to 16 KiB |
| OAuth requests per client address | 100 in 15 minutes |
| MCP requests per connection | 600 a minute |

## Questions and answers

**What is the difference between a connected app and an API key?**
A connected app is approved in the browser and holds tokens it renews by
itself; no secret is pasted anywhere. An API key is a secret you copy once. A
connected app works at MCP only. An API key works at MCP and REST.

**Which apps can I connect?**
Claude (including Claude Code) and Codex. Other MCP clients, such as Cursor,
connect with an API key.

**Can a member connect an app?**
Yes. Any member can, for the workspaces they reach. Only owners and admins can
grant "Set file statuses".

**Does the app see my password?**
No. You sign in to Talewright in your own browser. The app receives tokens,
never your password.

**What can the app do once connected?**
What you ticked, in the workspaces you ticked, as you. It cannot make files
public, delete for good, or manage people and credentials.

**Why is "Set file statuses" not ticked although the app asked for it?**
It always starts unticked. Tick it only if the app needs to set statuses.

**Why can I not tick "Set file statuses"?**
You are not owner or admin in every workspace you ticked.

**How long does a connection last?**
As long as you chose: 30, 90, 180 or 365 days. Then the app asks you again.

**Do I have to do anything every hour when the access token expires?**
No. The app renews it by itself with its refresh token.

**The app says it lost access after a month of not being used. Why?**
A refresh token stops working after 30 days without a refresh. Sign in again
from the app.

**How do I change what an app may do?**
Connect it again from the app and choose differently, then disconnect the
earlier connection. A new connection does not replace an old one.

**I use Claude Code on two computers. Do they share a connection?**
No. Each computer connects on its own and gets its own row under Connected
apps, told apart by when it was connected and last used. Disconnecting one
leaves the other working.

**How do I stop an app at once?**
**Settings > Connected apps**, "Disconnect". Its tokens stop working
immediately.

**What happens to the work an app did after I disconnect it?**
It stays. Files, changes and proposals are not undone.

**Can an owner disconnect my app?**
Yes. Owners and admins revoke any member's connected app in Key management.

**Can I connect the same app to two organizations?**
Yes. Each organization gets its own connection.

**Why does my access token not work with `curl` against `/v1`?**
Access tokens of connected apps work at `/mcp` only. Use an API key for REST.

**Do connected apps survive a password change?**
No. Changing or resetting your password disconnects all your apps and revokes
all your keys.

**Where do I see what an app did?**
"Activity" on its row under **Settings > Connected apps**.

**Is anyone told when an app is connected?**
You get a security email. Owners and admins see the app in Key management.

**I pressed "Deny" by mistake. What now?**
Start again from the app. A request is answered once.

**Can someone who gets hold of my consent link answer it?**
Not once you have opened it. A request belongs to the first signed-in account
that opens it; everyone else is told it has ended.

## Related pages

- [Credentials and scopes](credentials.md)
- [MCP](mcp.md)
- [The REST API](rest-api.md)
- [Roles and permissions](../reference/permissions.md)
- [Audit trail](../reference/audit-trail.md)
- [Errors](../reference/errors.md)
- [Limits](../reference/limits.md)

