Connecting External Services

If an agent needs to read your GitHub repos or write to a Notion page, it needs to log in to that service on your behalf. UpServe is designed so you only do this once. After that, any skill that uses the same service will reuse the credential automatically — you don’t log in again, and the credential is forwarded to the skill at runtime.

At a glance

How to connect

There are three places to connect an external service. Any of them produces the same result — use whichever is more convenient.

Path A — Connect from the Marketplace

1. Open a skill that needs OAuth (e.g. GitHub, Linear, Notion, Slack) on the Marketplace → Skills  page.
2. If the skill card shows a Connect Required prompt, click the button next to it.
3. The external service’s login screen opens. Review the requested permissions and approve — you return to UpServe automatically.
4. The card now shows the connected account name.

   [1] Open a skill that needs OAuth
        e.g. "GitHub Integration"
              │
              ▼
   [2] Click "Connect Required" on the card
              │
              ▼
   [3] Sign in + approve permissions
        (the service's own consent screen)
              │
              ▼
   [4] Auto-redirect back to UpServe
        Card shows the connected account name

Path B — Connect from Agent Settings

You can also connect while adding the skill directly to an agent.

1. Go to the agent page → Settings tab → open the Skill Selector.
2. Toggle the skill that needs OAuth ON.
3. An OAuth row appears below the skill card. The button state tells you where things stand:
   • Connect — not yet connected. Click to open the external service’s login screen.
   • Connecting… — redirect is in progress.
   • Reconnect — already connected or re-authentication is needed. Click to reopen the consent screen.
   • [Service] connected — active and ready.
4. Click Connect and approve the permissions on the external service’s screen. When you return, the connection row shows [Service] connected.

   [1] Agent Settings → Skill Selector
              │
              ▼
   [2] Toggle skill ON
              │
              ▼
   [3] OAuth row appears — click "Connect"
              │
              ▼
   [4] Sign in + approve permissions
              │
              ▼
   [5] Auto-redirect — row shows "[Service] connected"

Path C — Connect from a card in the chat

This is the most common path. When an agent runs into a task that needs a service it isn’t connected to yet, it shows a Connect card right in the conversation.

1. Mid-task, the agent posts a card in the chat with a Connect [Service] button.
2. Click that button to open the external service’s login screen (the same consent flow as Path A and Path B).
3. Approve the permissions and return — the agent picks up the task where it left off.

   [1] Agent needs a service it isn't connected to
              │
              ▼
   [2] "Connect [Service]" card appears in the chat
              │
              ▼
   [3] Click the button → sign in + approve permissions
              │
              ▼
   [4] Auto-redirect — the agent resumes the task

You only connect each service once. If a second skill that uses the same provider is toggled on later, it reuses the existing connection without a new sign-in.

What happens after connecting

• Whenever an agent runs a skill that uses the connected service, UpServe fetches a valid access token and hands it to that skill.
• The token is cleaned up at the end of the skill’s run. It’s fetched fresh next time.
• Tokens close to expiry are refreshed in the background, so work in progress rarely stalls.
• If the external service revokes access (e.g. you changed your password, or removed the integration from the provider’s settings), the skill card shows Reconnect required. Clicking it reopens the consent flow.

Disconnect / re-authenticate

To disconnect, use the Disconnect button on a connected skill card on the Marketplace → Skills  page. The button appears next to the connected account name when a service is already linked. Clicking it removes the connection immediately.

The OAuth row inside the agent’s Skill Selector only offers a Reconnect button — that reopens the consent screen to re-authenticate, it does not disconnect. If you need to remove a connection, go to the Marketplace skill card.

After disconnecting, any skill that uses that service will ask you to connect again on its next run. To swap to a different account, disconnect and then reconnect with the new one.

Note — Disconnecting removes the connection for all of your agents that use that service. It has no effect on other users or teammates — credentials belong to your account only.

Saved keys (credentials you store yourself)

Even for services without a prebuilt connection, you can store an API key or token so an agent reuses it across tasks — for example, save a payment-service API key once and the agent uses it without asking again.

• How to save (in chat) — when you enter a value with the lock button in the chat box, turn on “Save for this agent to reuse later” and give it a name (e.g. STRIPE_API_KEY).
• Manage — view and delete them per agent under the Saved keys section in Settings → Connections .
• Private to the agent — a saved key is used only by that agent; it is never shared with other agents or users.
• Never shown again — for security, the stored value is never displayed again. To change it, delete and save a new one.
• No auto-refresh — unlike the OAuth connections above, a key you store yourself does not refresh automatically. Replace it when it expires.

One-time secrets (values that are not stored)

For values you don’t want kept — a password or a verification code — send them with the lock button but leave the save option off. Your plaintext value is not stored; the encrypted value is automatically deleted a short time later (up to 15 min). Only the label and a masked placeholder remain in the conversation.

Security

• Per-user isolation — credentials are stored against your account only. Other users, including teammates, cannot access them.
• Saved keys are per-agent — a key you store yourself is encrypted for that agent only and is never exposed to external visitors of a shared link.
• The agent never sees the raw token — tokens are passed to the skill’s execution environment as environment variables only, and cleaned up when the run ends. They are not echoed into chat messages or logs.
• Encrypted at rest — both the access token and refresh token are encrypted before being saved to the database.
• Standard OAuth + CSRF-safe — UpServe uses the standard Authorization Code flow and rejects forged callbacks.

Advanced

The rest of this page describes internal behavior — useful if you author skills directly or need to debug an integration. Day-to-day users can skip it.

Permissions requested per service

UpServe asks for the following scopes (user-facing summary; the actual consent screen comes from each service):

The consent screen is always the external service’s official page. The exact scopes granted are stored alongside the connection.

How skills receive the credential

You only need this if you author skills directly or want to understand an imported skill’s internals. A skill’s SKILL.md declares the credentials it needs under metadata.requires, and at run time UpServe injects a valid token (refreshed first if near expiry) as an environment variable, then cleans it up when the run ends. Agents fill this field in automatically when packaging a skill, so you rarely edit the yaml yourself. See Creating Skills → Secret injection for the mapping table and examples.

Google Drive Picker

When a skill or agent action needs to access Google Drive files, UpServe uses the Google Picker — a file selector that runs inside your browser under your Google account. Only the files you explicitly select through the Picker are accessible; UpServe does not request access to your entire Drive. This is enforced by the drive.file scope, which is limited to files the user has opened or created through the app.

Token expiry and refresh

• When an access token is close to expiry (5 minutes before expiry), UpServe uses the stored refresh token to mint a new one.
• Refresh happens just before the skill runs, so the new token is the one handed to the skill.
• If refresh fails (the user revoked access externally, or the refresh token was rotated out), the connection is marked inactive and the skill card surfaces a Reconnect required prompt for the user to consent again.