MCPApps and Services

You are viewing the docs for Archestra v1.4. View the latest docs

Gateway Access for Apps

Give your app its own identity in Archestra, not a person's token. A support bot, a nightly job, or an internal portal gets an OAuth client. You choose the gateways and agents it reaches. Its tokens expire, and you can rotate its secret at any time.

Pick how it signs in by who is behind each call:

How it signs inEach call acts asExample
As itself (client credentials)The app or a selected service accountA bot that triages tickets every night
For its users (authorization code)The person signed in to your appAn internal portal where people ask an agent questions

Create either one under Settings → OAuth Clients → Create OAuth Client, or from a gateway's Connect tab.

Call as the App

Each application owns its A2A tasks and retained runtime workspaces. Use the same application's credentials to list, read, follow, or cancel its tasks; tokens renewed for that application retain access. A different application cannot access those tasks, even when both can call the same agent.

Select Service account (optional) under Advanced on the create dialog's Access step to give an automation one identity across OAuth and REST API keys. Its A2A tasks and runtime workspaces belong to that account: OAuth credentials and API keys for the same account can read, follow, or cancel those tasks. Other accounts cannot access them. Use the account's API key on the platform API to manage its runs and delete its own retained workspaces.

The client's allowed agents and gateways still limit OAuth access, and the service account must also have permission to use each resource. Disabling the account stops its OAuth requests; changing the binding revokes issued OAuth tokens. In the edit dialog, the selector is under Access.

For LLM Proxy access, enable LLM Proxy on the same client and select provider keys on Access. Its service-account binding covers all enabled APIs. Spend from that client and runtime virtual keys is attributed to the account. Binding does not supply upstream credentials.

No person signs in, so the app uses the gateway's shared accounts. Give its tools a shared service account in Choose Its Tools.

  1. Create an OAuth client. Under What can it access?, select MCP Gateway for tools, A2A for agent calls, or both. Pick As itself. On Access, select the gateways and agents it may reach and optionally open Advanced to select a service account.

  2. Save the client ID and secret in your secret store. The secret shows only once.

  3. Get a token. This example calls MCP; use scope=a2a for agent calls:

    bash
    curl --request POST "$ARCHESTRA_URL/api/auth/oauth2/token" \
      --data-urlencode 'grant_type=client_credentials' \
      --data-urlencode "client_id=$CLIENT_ID" \
      --data-urlencode "client_secret=$CLIENT_SECRET" \
      --data-urlencode 'scope=mcp'
    
  4. Call the gateway with Authorization: Bearer <access_token>. Get a new token when it expires.

Reuse each token until it expires. If the token endpoint returns HTTP 429, wait for its Retry-After delay before requesting another token. See authentication rate limits.

Call for a Person

Each call acts as the person signed in to your app, with their own tools and accounts. A ticket the agent files shows their name, not the app's.

  1. Create an OAuth client. Select its capabilities and For its users. On Access, add your app's redirect URIs.
  2. In your app, run the authorization code flow with PKCE and the client secret. Ask for scope=mcp for tools or scope=a2a for agent calls. Add offline_access to get a refresh token.
  3. Call the gateway with the person's access token.

On Access, leave Additional gateways and agents (optional) empty to use each person's own access. Selecting resources adds access for everyone who signs in through your app, even without their own access.

Choose Token Scopes

Ask for only the enabled capabilities each token needs:

ScopeAPI
mcpMCP Gateway
a2aAgent A2A endpoints
llm:proxyLLM Proxy and Model Router

For example, scope=mcp llm:proxy gets one token for tools and inference. Each requested scope must be enabled on the client. Omitting scope in a client credentials request grants all its configured capabilities. A token cannot gain a capability added after it was issued; request a new token. Removing a capability or disabling the client blocks its use immediately.

Open an existing client and use Access to change its capabilities, gateways, agents, or provider keys. The client ID and secret stay the same.

In Settings → OAuth Clients, use All APIs to find clients for a particular API. A client with several capabilities appears under each matching filter. The MCP Gateway, A2A, and LLM Proxy columns summarize its targets and provider access; clients that sign users in use each person's access.

What to Know

  • Secret leaked? Open the client and click Rotate secret. The old secret stops working.
  • An application can use the same client ID and secret for several APIs. Select LLM Proxy as well, then configure its provider keys. See LLM Proxy authentication.