Talewright Docs Open the app

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.

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

Who can do what

ActionOwnerAdminMemberSigned-in personCredentialScope a credential needs
Allow or deny an app's request to connectYesYesYesYesNoBrowser only
Grant an app files:approveYesYesNoNoBrowser only
List your connected appsYesYesYesYesNoBrowser only
Disconnect one of your connected appsYesYesYesYesNoBrowser only
Read the activity of your connected appYesYesYesYesNoBrowser only
List every member's connected apps (Key management)YesYesNoNoBrowser only
Revoke any member's connected appYesYesNoNoBrowser only
Call MCP tools as the connected appYesThe scopes granted at consent
Revoke its own tokens (the app itself)YesNone: 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.

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 and Roles and permissions.

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:"

    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:

    [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 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."

FieldWhat 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:

ScreenWhen
"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.

EndpointPurpose
GET /.well-known/oauth-protected-resource/mcpDescribes the MCP endpoint as a protected resource.
GET /.well-known/oauth-authorization-serverDescribes the authorization server.
GET /oauth/authorizeStarts a request to connect. Opened in the person's browser.
POST /oauth/tokenExchanges a code, or refreshes tokens.
POST /oauth/revokeRevokes 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:

PropertyValue
authorization_endpoint, token_endpoint, revocation_endpointThe three /oauth/ addresses
response_types_supportedcode
response_modes_supportedquery
grant_types_supportedauthorization_code, refresh_token
code_challenge_methods_supportedS256
token_endpoint_auth_methods_supportednone
scopes_supportedworkspace:read, files:read, files:write, files:approve
client_id_metadata_document_supportedtrue
authorization_response_iss_parameter_supportedtrue

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):

ParameterRequiredValue
client_idYesThe client ID address.
redirect_uriYesOne of the document's addresses.
response_typeYescode
code_challengeYesThe PKCE challenge: 43 base64url characters.
code_challenge_methodYesS256
resourceYesThe MCP endpoint's URL, exactly as the discovery document gives it.
scopeNoSpace-separated scopes. Without it: workspace:read files:read files:write.
stateNoUp 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:

FieldValue
grant_typeauthorization_code
client_idThe client ID address.
codeThe code from the redirect.
redirect_uriThe same address as in the authorization request.
code_verifierThe PKCE verifier: 43 to 128 unreserved characters.
resourceThe MCP endpoint's URL. Required.

Refreshing:

FieldValue
grant_typerefresh_token
client_idThe client ID address.
refresh_tokenThe current refresh token.
resourceOptional. If sent, the MCP endpoint's URL.
scopeOptional. If sent, exactly the scopes the connection holds.

The answer:

{
  "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:

{
  "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"
  }
}
OperationCapabilityAccess
GET /v1/oauth/requests/{requestID}credential.oauth_requests.getBrowser only
POST /v1/oauth/requests/{requestID}/decisioncredential.oauth_requests.decideBrowser only
GET /v1/me/connected-appscredential.connected_apps.listBrowser only
DELETE /v1/me/connected-apps/{credentialID}credential.connected_apps.disconnectBrowser 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.
  • 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.

WhereErrorMeaningWhat to do
"This app cannot connect"unauthorized_clientTalewright does not accept this app.Use an accepted app, or an API key.
"This app cannot connect"invalid_clientThe app's document could not be read or is not valid.The app's developer must fix it.
"This app cannot connect"invalid_redirect_uriThe return address is not listed by the app.The app's developer must fix it.
"This app cannot connect"invalid_requestThe request has no client_id.The app's developer must fix it.
Back at the appaccess_deniedYou pressed "Deny".Nothing.
Back at the appinvalid_request, unsupported_response_type, invalid_target, invalid_scopeThe app's request is malformed.The app's developer must fix it.
Token endpointinvalid_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 endpointinvalid_client (401)No client_id, or a secret was sent.The app's developer must fix it.
Token endpointinvalid_scope, invalid_target, invalid_request, unsupported_grant_type (400)The token request is malformed.The app's developer must fix it.
Any /oauth/ endpointRATE_LIMITED (429)More than 100 requests from one address in 15 minutes.Wait for Retry-After.
ConsentNOT_FOUND (404)The request is unknown, answered, older than 10 minutes, or was first opened by another account.Start again from the app.
ConsentFORBIDDEN (403)A member tried to grant files:approve, or a bearer token called a consent operation (SESSION_REQUIRED).Untick it, or use a browser.
ConsentVALIDATION_FAILED (422)organizationID, workspaceIDs, scopes (including one the app did not ask for) or expiresInDays.Correct the field and decide again.
ConsentCONFLICT (409), reason CONNECTION_LIMITYou already have 10 working connections to this app in this organization.Disconnect one, then allow again.
MCPUNAUTHENTICATED (401)The access token expired, or the app was disconnected.The app refreshes, or asks you again.

Limits

LimitValue
Time to answer a request10 minutes
Code lifetime60 seconds, one attempt
Access token lifetime60 minutes
Refresh token lifetime30 days without a refresh
Connection lifetime30, 90 (default), 180 or 365 days
Workspaces per connection1 to 20
Working connections per member, app and organization10
stateUp to 500 characters
App name shownUp to 100 characters
App documentUp to 16 KiB, read within 5 seconds, 1 to 20 return addresses
Token request bodyUp to 16 KiB
OAuth requests per client address100 in 15 minutes
MCP requests per connection600 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.