Credentials API

Connect OAuth services, service accounts, and MCP servers for your workspace. Credentials supply tokens and keys to apps and agents at run time.

→ Extend credentials — declare requirements in inf.yml
→ Connectors overview — MCP connectors and agent tools

Requires API key scopes credentials:read (list, capabilities, check) and credentials:write (connect, disconnect, call tools).

Paths under /integrations (the name before 2026-09-23) answer 410 Gone with a Link header naming the /credentials path.

Connect stores non-OAuth credentials (service accounts, MCP bearer tokens) and OAuth tokens in encrypted JSON on the credential row — tokens are never returned in API responses. Disconnect loads stored tokens, calls provider cleanup when supported, then soft-deletes the connection.

MCP tool proxy (/mcps/{slug}/tools) is not part of the credentials namespace.

Vaults

Credentials and secrets are grouped into vaults. Workspace- and user-scoped credentials are linked to the workspace's default vault when they are created. Workspace-scoped secrets are linked on create as well. Use GET /vaults/{id}/credentials and GET /vaults/{id}/secrets to list members, and the POST/DELETE membership endpoints to manage links without deleting the underlying credential or secret.

Capabilities catalog

GET /credentials/capabilities

Returns credential keys your apps can declare (for example google.sheets, google-sa.files). Each capability includes provider, type, OAuth scopes, and whether it is available on this server.

1curl https://api.inference.sh/credentials/capabilities \2  -H "Authorization: Bearer inf_your_key"

Response:

1{2  "capabilities": [3    {4      "key": "google.sheets",5      "provider": "google",6      "type": "oauth",7      "scopes": ["https://www.googleapis.com/auth/spreadsheets"],8      "display_name": "Google Sheets",9      "available": true10    }11  ]12}

Use this to build setup UIs or validate inf.yml credential keys before deploy.

Credential configs

GET /credentials/configs

Returns the merged credential view: the provider catalog joined with your workspace's connection state in one response. Each registered provider (OAuth, BYOK, service accounts) appears once with catalog metadata (display names, descriptions, icons, docs links, BYOK form fields, has_managed, connection_scope) and, when connected, a nested credential object with live status, account info, and OAuth scopes. accounts lists every login you can use for the provider. credential is accounts[0]: the login GET /credentials/{provider} returns without identifier, which is the connected login a run would use when there is one, otherwise the first login on the resolution ladder (for example a disconnected key login that still needs its keys), so a setup UI can prompt for them. The other entries follow the ladder (your own before the workspace's, each owner's default before its other accounts, then oldest). A disconnected or expired personal login is not shown as the active login while a connected workspace key is what runs use. OAuth providers may also include an app object — the OAuth application row (client id/secret), separate from the login in credential. Each entry has a unique slug (for example google, google-sa, gcp, slack). Providers whose default connection_scope is user include your personal connection in credential when you are authenticated.

Connected MCP servers are appended as standalone rows at the end of the array: provider is mcp, slug is the server's slug, and credential.account_identifier is the server URL.

Requires credentials:read.

1curl https://api.inference.sh/credentials/configs \2  -H "Authorization: Bearer inf_your_key"

Response (array of config objects):

Native providers (OAuth, BYOK, service accounts) appear once per credential slug. MCP servers are not in the provider catalog, but MCP entries (type: "mcp", provider: "mcp", slug = the workspace's server slug when it has one) are included for every server the caller has connected, and for every server host whose OAuth app is set up but nobody has connected yet: that entry carries app, no credential, secret_fields for the app's client id and secret, and connection_scope: "user". A connected MCP entry also carries app when its host has one. To browse or connect new MCP servers, use the MCP servers API or POST /credentials with provider: "mcp".

For MCP browse and connect UIs, authenticated GET /mcps and GET /mcp-servers responses carry connection_status for each server_url. Use those endpoints instead of merging this configs array with MCP server lists.

Provider names are globally unique for native providers, and each maps to exactly one connection type. MCP supports several connections per workspace under the one provider mcp, told apart by account_identifier (the server URL); name one with ?identifier={server_url} on get and disconnect. Use slug for dashboard links and provider for POST /credentials, GET /credentials/{provider}, and DELETE /credentials/{provider}.

JavaScript SDK: client.credentials.getConfigs()

Company catalog

GET /companies · GET /companies/{slug}

The companies behind credential slugs (company.slug on a config). A company has one or more auth providers (Google: google, google-sa, google-gemini, …). Public: no API key required. GET /companies takes an optional category query parameter (ai_ml, media, search, cloud, social, tools). GET /companies/{slug} returns one entry, or 404 for an unknown slug.

Before INF-1079 these were GET /providers and GET /providers/{slug}. Those paths are no longer served; use GET /companies and GET /companies/{slug}.

1curl https://api.inference.sh/companies?category=ai_ml2curl https://api.inference.sh/companies/google

Each entry (CompanyDTO):

Available providers

GET /credentials/available

Returns a simple list of provider names that can be connected on this server (for example google, google-sa, gcp, slack). Requires credentials:read.

1curl https://api.inference.sh/credentials/available \2  -H "Authorization: Bearer inf_your_key"

JavaScript SDK: client.credentials.listAvailable()

List connected credentials

GET /credentials or POST /credentials/list

Cursor-paginated list of credentials connected for your workspace (and per-user connections when applicable). Use this when you need to page through all connections or look up a single provider by key. For setup UIs that show catalog metadata alongside connection state, prefer GET /credentials/configs, which returns the merged view in one call.

1curl https://api.inference.sh/credentials \2  -H "Authorization: Bearer inf_your_key"

CLI equivalent: belt credentials list (add --limit and --cursor to page; table mode prints next page: / prev page: hints with the cursor value). The table's columns are company, slug (credential / provider slug), sign-in, status, owner, and keys, and it also lists OAuth apps set up for a slug nobody has connected yet. With --json, stdout is the current page's items array; --json --apps prints {"items": [...], "apps": [...]}. The CLI calls POST /credentials/list and reads each row's company from configs.

GET /credentials/{provider} returns a single credential by provider key (for example google, google-sa, gcp, slack, mcp). When a provider has several accounts, ?identifier= names one (for MCP, the server URL); without it you get the default.

Optional identifier selects one login when several accounts are connected for the same provider. Pass the provider's stable account_id (for example Google's sub, an X user id, or an MCP server URL) or the display label in account_identifier (email, @handle, …). Prefer account_id when the credential object includes it — labels can change and legacy logins may have been created before ids were stored. Omit identifier to get the default login for that provider.

1curl https://api.inference.sh/credentials/google \2  -H "Authorization: Bearer inf_your_key"34curl 'https://api.inference.sh/credentials/google?identifier=user%40company.com' \5  -H "Authorization: Bearer inf_your_key"67curl https://api.inference.sh/credentials/google-sa \8  -H "Authorization: Bearer inf_your_key"

CLI equivalent: belt credentials get <provider> (for example belt credentials get google, belt credentials get google-sa, or belt credentials get mcp). The CLI calls GET /credentials/{provider} and best-effort merges GET /credentials/configs so table output can show the provider name, linked company (company), website, and docs.

JavaScript SDK: client.credentials.get(provider) — same response as the REST endpoint.

Credential object fields

Each connected credential (CredentialDTO) includes:

A credential row exists only once it holds a login (OAuth sign-in completed) or a key login was started by saving a key. The API creates no empty placeholder rows: not when an agent run is blocked on a provider (the blocked tool waits in the chat until you connect or save keys), not when you start OAuth. Saving a key creates a disconnected login that turns connected once its keys are stored. Deploying an app whose declared keys are missing creates a login only when deploy can adopt unlinked vault secrets onto it; otherwise the next run asks for the keys and saving them creates the login. The pending status (a keyless placeholder login) is no longer written, and the remaining placeholder rows were retired on 2026-10-28. Runs that require a credential use only connected logins.

Raw tokens are never returned. Workspace-scoped credentials (scope: "team") are shared connections created by connect flows; user-scoped rows (scope: "user") are personal OAuth logins (grant: "token"); org-scoped rows (scope: "org") are shared across all workspaces in the organization; platform-scoped rows (scope: "platform") are platform keys inference.sh provides (managed credentials when has_managed is true on the provider config). When several rows match at run time, secrets passed with the task come first, then your own user connection, then the workspace team default login (is_primary: true, else oldest), then org, then a platform key. A platform-scope login is on the lookup ladder only in the platform workspace; other workspaces get platform keys through the run-time access list below, never as a login they can read or name. Each platform key has an access list deciding which other workspaces' runs may use it: which apps and functions, store-reviewed versions only, on cloud infrastructure only. When no key admits the run, the requirement stays unmet and POST /run returns 412; add your own key for that provider.

Multiple accounts per provider

OAuth and other account-based providers can have several logins for the same owner (for example two Google accounts on one workspace). Connecting another account adds a new login instead of replacing the first.

MCP servers remain one row per server URL (provider: "mcp", account_identifier = the server URL). Each MCP connection is its own server, not another account of a shared provider slug.

Only platform admins can replace or remove a platform credential, and only org admins an org credential. A shared team credential needs the workspace admin role unless you created it. When allows_byok is true on the provider config, a workspace can override an inherited credential with its own: OAuth providers via POST /credentials, and api_key providers by saving a workspace secret with the provider field set (see Create secret). For api_key providers the credential's status is connected while at least one linked key secret exists and disconnected after the last one is removed.

API key lifetime

An api_key auth provider (or an app's credentials: entry) can set expires_after_days. It is copied to expires_after_days on GET /credentials/configs.

Once expires_at has passed, the login reads as expired, its key is not injected at run time, and POST /credentials/check and 412 responses ask for a new key (your {name} key expired on {date}; add a new one), with the provider's instructions on the action. A login with no expires_at never expires this way.

OAuth logins use the same expires_at field for the access token, unrelated to expires_after_days.

Managed credentials and grant type

Each config entry exposes connection_scope — who owns new connections by default. Use it for setup copy:

When the provider signs in through an OAuth application, app holds that app row (grant: "credentials" — client id/secret only, not a login). credential holds the login (grant: "token" for OAuth connections). Completed OAuth stores which app was used on the login as app_credential_id.

grant on CredentialDTO (including nested app and credential objects) distinguishes app rows from connection rows:

grant=credentials is only valid for type: "oauth" app rows. Per-user OAuth providers use connection_scope: "user" on the config; each member's login appears in credential with scope: "user".

Check scope on the connected CredentialDTO to distinguish personal vs workspace connections in list and detail UIs.

When a provider signs in through an OAuth app, new logins use the first complete app in this order: the workspace's own (scope: "team"), then the organization's (scope: "org"), then the platform's (scope: "platform"). GET /credentials/configs returns that choice in app. Refresh tokens always use the app that issued the login (app_credential_id on the login row).

Configure OAuth app

OAuth providers whose config includes secret_fields (for example SLACK_CLIENT_ID / SLACK_CLIENT_SECRET) require an OAuth application row before POST /credentials can return an auth_url. The app holds client credentials only (grant: "credentials"); user and workspace logins stay separate (grant: "token" in credential).

Set or update app

PUT /credentials/{provider}/app

Requires credentials:write and the workspace admin role (platform operators on the platform workspace when setting a platform app). The body is a CredentialAppRequest:

The app row's status becomes connected once both the client id and client secret keys are non-empty. Register the provider's redirect URI in the third-party console (for example https://app.inference.sh/settings/secrets/oauth/{slug}).

1curl -X PUT https://api.inference.sh/credentials/slack/app \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{5    "values": {6      "SLACK_CLIENT_ID": "123.456",7      "SLACK_CLIENT_SECRET": "abc..."8    }9  }'

Response: CredentialDTO for the app row (grant: "credentials").

Remove app

DELETE /credentials/{provider}/app

Deletes the caller's own OAuth app row for the provider (workspace or platform scope) and removes linked vault secrets. Requires the same admin roles as PUT. Responds 400 validation_error when one or more logins still reference the app — disconnect those connections first — and 404 when you have no app row of your own for the provider.

Allowed scopes

An OAuth app can carry allowed_scopes: the list of scopes a login through that client may request. The platform's clients are restricted to the scopes the provider has approved them for (the platform's Google client, for example, to the scopes it passed Google's verification with); a workspace's or org's own client has no list and is unrestricted unless its admin sets one.

• Empty or absent: any scope. This is what a workspace's own client gets by default.
• Set: every scope a connect or add-scopes request names, after the auth method's required_scopes are merged in, must be on the list. Scopes are compared in the method's wire form, so an alias (gmail.send) and the provider's own form (https://www.googleapis.com/auth/gmail.send) name the same scope, on the list and in the request. The method's required_scopes (identity and refresh) are never refused.

The check runs before any authorize URL is built. On connect, the app is the one a new login uses: the caller's workspace client, else its org's, else the platform's. On add scopes, it is the app that issued the login (app_credential_id); a login with no stored app uses the one a new connect would take. Widening a login never moves it to another client, because a refresh token works only with the app that issued it. A request for a scope outside that app's list is refused with 400 validation_error:

1{2  "error": "validation_error",3  "detail": "scope https://www.googleapis.com/auth/youtube.readonly is not approved for the platform's Google client; connect through your own OAuth app or ask an admin"4}

Either set up your own OAuth app for the provider with PUT /credentials/{provider}/app (logins then go through it, with no list) or ask a platform admin to approve the scope. Platform admins edit the platform client's list in the admin console or as data through PUT /admin/credentials/{provider} with allowed_scopes (the response is the app row); a workspace admin edits their own client's list in the vault's OAuth app dialog (allowed scopes) or through PUT /credentials/{provider}/app.

A deploy whose inf.yml asks the platform's client for a scope outside its list is accepted with a unapproved_platform_scope deploy warning; the connect is where it is refused.

Optional app keys

Some providers take extra keys on the OAuth app (the auth method's app_keys: signing secrets, bot tokens, tenant ids). Store them in the same values map on PUT /credentials/{provider}/app as the client id and secret, for example SLACK_SIGNING_SECRET and SLACK_BOT_TOKEN for Slack (Slack guide).

When the API needs one of these keys (channel webhook verification, outbound messages, provider-specific OAuth steps), it reads them from the OAuth app in use for the provider: the app a login was made through, else the one a new login would use (workspace, org, then platform). When the provider has such an app, its keys are the only source. Only when there is no app does the API fall back to a workspace secret with the same key name, then to keys on the caller's personal (scope: "user") login for the provider.

Connect a credential

POST /credentials

Starts OAuth, creates a service account, or registers an MCP server connection.

OAuth providers

1{2  "provider": "google",3  "type": "oauth",4  "scopes": ["https://www.googleapis.com/auth/spreadsheets"]5}

To connect a second Google account on the same workspace, set another_account: true so the provider shows its account chooser:

1{2  "provider": "google",3  "type": "oauth",4  "scopes": ["https://www.googleapis.com/auth/spreadsheets"],5  "another_account": true6}

Client credentials. When the slug's auth method is oauth2 with flow: client_credentials, there is no browser step: the API exchanges the slug's client id and secret at the token endpoint and the response carries credential with status: "connected". The token is re-minted before it expires. api_key and http methods are not connected here: save their fields with POST /secrets and provider set to the slug (the same path as catalogued API-key providers; see Secrets API).

Response when the user must complete OAuth in a browser:

1{2  "auth_url": "https://accounts.google.com/o/oauth2/v2/auth?...",3  "state": "state_abc123",4  "code_verifier": "..."5}

Open auth_url, then complete the flow with POST /credentials/oauth/complete:

1{2  "provider": "google",3  "type": "oauth",4  "code": "authorization_code",5  "state": "state_abc123",6  "code_verifier": "..."7}

Some providers add extra query parameters on the redirect (QuickBooks realmId, Shopify shop, and so on). Pass them in optional params on the complete request (every key except code and state, which stay top-level). Auth method templates read them as {{callback.*}} — see Callback query parameters on OAuth complete.

Omit code_verifier when you started connect with the same state — the API stores the PKCE verifier from POST /credentials and claims it when completing OAuth. Pass code_verifier explicitly when your client held it locally and did not use the server-stored challenge.

Account identity on OAuth complete

When the slug's auth method says how to learn the account (identifier or identity_hook), completing OAuth must yield a non-empty account. If the provider answers the identity lookup without one (a 401 or 403, or a 200 with no matching field), the connect fails and nothing is saved. The response is 500 internal_error with the generic detail failed to complete OAuth flow. The usual cause is an OAuth app or grant missing the scope the userinfo or lookup endpoint needs: fix the app permissions or scopes and connect again.

Temporary lookup failures are different. When the identity lookup times out, cannot reach the provider, or gets 408, 429, or 5xx, and the lookup URL is the auth method's own (not one named by the token response), the login is saved without an account. The API asks the provider again when the login is next used, at most every 15 minutes, and then fills account_id, account_identifier, account_name, and metadata. When the lookup URL came from the token response, a temporary failure fails the connect like a refusal.

Auth methods that do not define identifier or identity_hook can still connect without an account id (unusual for user OAuth).

When reconnecting an expired or error credential, you can call POST /credentials with the same provider and an empty scopes array (or omit scopes). The API carries forward previously granted scopes in the OAuth consent URL so the user restores all permissions in one step instead of starting from zero.

Completing OAuth (POST /credentials/oauth/complete) for an existing login — reconnect, incremental scope grant, or MCP re-authorization — updates that row in place. The credential id, vault membership links, and anything that references the id stay put. New tokens, scopes, account fields, and status change. Only disconnect removes the row; the next connect creates a new id. One exception: a login saved without an account that later learns an account another login of the same owner already has is folded into the older login, and the newer id is retired (see Multiple accounts per provider).

Required scopes on connect

OAuth slugs resolve through an auth provider and its oauth2 auth method. When you pass scopes on connect, the API still merges the method's required_scopes into the authorize URL. Those permissions are not optional: they let the platform read account id and display name after token exchange (and request refresh tokens when the method defines them).

Without them the provider can refuse the identity lookup, and then the connect fails and nothing is saved (see Account identity on OAuth complete). Built-in providers (Google, Microsoft, X, Discord, GitLab, LinkedIn, Linear, Atlassian, Xero, and others) declare required_scopes on their platform row. A team's own auth provider should set required_scopes in auth_methods when identity templates depend on specific grants.

The same merge applies on POST /credentials/{provider}/scopes: requested scopes plus required_scopes go to the provider.

Connection scope

Optional connection_scope on POST /credentials sets who owns the resulting credential. It is separate from scopes, which are OAuth permission scopes.

1{2  "provider": "google",3  "type": "oauth",4  "scopes": ["https://www.googleapis.com/auth/spreadsheets"],5  "connection_scope": "team"6}

Omit connection_scope to use the provider's default: the scope the provider declares (user for MCP), user for grant=credentials providers, team otherwise.

Choose connection_scope at connect time, or on POST /secrets when saving a BYOK API key with provider. To change who owns an existing connection without revoking tokens, use Change connection scope.

For OAuth flows the chosen scope is stored server-side with the OAuth state and applied when oauth/complete runs. The completing client does not resend connection_scope.

Service accounts

Google Sheets/Docs/Drive service accounts use the google-sa provider (separate from Google OAuth's google and GCP WIF's gcp):

1{2  "provider": "google-sa",3  "type": "service_account"4}

Returns credential when the connection is created immediately (no redirect). Declare google-sa.files in inf.yml (replaces the former google.sa and interim gcp.sa capability keys). Existing workspace connections that used provider: "google" or provider: "gcp" with auth: "service_account" were migrated to google-sa in a one-time database update, so no reconnect is required.

Custom MCP servers

Connect an arbitrary HTTPS MCP endpoint (same flow as belt mcp connect):

1{2  "provider": "mcp",3  "type": "mcp",4  "metadata": {5    "server_url": "https://mcp.example.com"6  }7}

For bare origins, the API may resolve the MCP path via /.well-known/mcp-server-card or UCP discovery — see Browsing connectors.

CLI equivalent: belt credentials connect <provider> (for example belt credentials connect google). The CLI resolves the provider from GET /credentials/configs. OAuth providers open a browser and poll until connected. api_key providers are not connected through this endpoint — the CLI collects each declared key and saves it with POST /secrets (belt secrets set <KEY> --provider <provider>). MCP servers use belt mcp connect <slug> instead. belt creds and belt integrations are aliases for belt credentials.

Bearer token / API key connect

When the remote MCP server accepts a pre-issued bearer token (API key, personal access token, or similar) instead of OAuth, pass it in metadata.bearer_token. The API skips OAuth discovery, stores the token as an encrypted workspace secret, and returns credential immediately:

1{2  "provider": "mcp",3  "type": "mcp",4  "metadata": {5    "server_url": "https://mcp.example.com",6    "bearer_token": "your-api-key-or-pat",7    "display_name": "My MCP Server"8  }9}

The connect response omits the token. Use GET /credentials/mcp?identifier={server_url} or belt credentials get mcp to confirm the connection is connected before calling tools.

→ Browsing connectors — API key servers

Connect errors

When the API can't sign in to the server, connect answers 400 with a validation_error whose detail says what went wrong:

1{2  "type": "https://api.inference.sh/errors/validation_error",3  "title": "Bad Request",4  "status": 400,5  "detail": "https://app.example.com/settings/mcp did not answer as an MCP server with OAuth sign-in. ..."6}

When OAuth discovery doesn't work for a server, set its OAuth app up by hand with PUT /credentials/mcp/app and connect again.

MCP OAuth client identity

When the remote MCP server requires OAuth, the API acts as a public OAuth client (PKCE, no client secret). Client identity is resolved in this order:

1. BYOK: oauth_client_id on a workspace MCP server registration, or a platform-managed secret keyed by hostname
2. Client ID Metadata Document (CIMD, SEP-991): when the authorization server advertises client_id_metadata_document_supported, the API uses the metadata document URL on the app origin as client_id (no Dynamic Client Registration)
3. Dynamic Client Registration (DCR): registers a new client when the server exposes a registration endpoint and CIMD is unavailable

The CIMD document is public (no API key). It is served on the app origin, so client_id shares an origin with client_uri and the redirect URI (some authorization servers require that):

1GET https://app.inference.sh/.well-known/mcp-client.json

The app serves this path by proxying the document the API builds at GET https://api.inference.sh/.well-known/mcp-client-app.json (same JSON body and Cache-Control; 502 with Cache-Control: no-store when the API does not answer).

1{2  "client_id": "https://app.inference.sh/.well-known/mcp-client.json",3  "client_name": "inference.sh",4  "client_uri": "https://app.inference.sh",5  "redirect_uris": ["https://app.inference.sh/settings/secrets/oauth/mcp"],6  "grant_types": ["authorization_code", "refresh_token"],7  "response_types": ["code"],8  "token_endpoint_auth_method": "none"9}

The client_id URL must match the document location. On self-hosted deployments, set APP_URL on the API to the public app base URL (for example https://app.example.com), and serve /.well-known/mcp-client.json on that origin from the API's /.well-known/mcp-client-app.json. If APP_URL is unset, CIMD is disabled and the connect flow falls back to DCR or BYOK credentials.

GET https://api.inference.sh/.well-known/mcp-client.json (the same document with the API origin as client_id) stays for MCP connections registered under that id before; they refresh with it.

When CIMD and DCR are unavailable (for example Microsoft Entra ID), connections need a registered OAuth application for the MCP server's host — see Configure MCP OAuth app below.

Authorization server profiles

MCP OAuth does not use an auth provider row. After discovery, the API selects an authorization server profile from the authorization server's metadata (issuer host, then authorize URL host, then token URL host). Unmatched servers use the standard profile (discovered endpoints, RFC 8707 resource on authorize, no scopes on refresh).

Profiles encode provider-specific rules: how authorize and token URLs are built from app fields, whether a resource parameter is sent, whether scopes are resent on refresh, extra app form fields, admin consent links, and how error responses are classified. The profile name is stored on the OAuth flow state and on the connection's metadata.as_profile after connect. Profile names are listed under auth_server_profiles in GET /auth-providers/hooks.

Today the API registers microsoft_entra for Microsoft Entra ID authorities (login.microsoftonline.com and related hosts). Entra apps may include a tenant_id field for single-tenant registrations; multi-tenant platform apps use the organizations tenant segment. Entra does not use the resource parameter and repeats scopes on token refresh.

Configure MCP OAuth app

Some MCP servers sign in through an authorization server that offers neither CIMD nor dynamic client registration. Others publish no OAuth discovery metadata at all. For both, configure an OAuth application per MCP host (not per workspace MCP registration row); for the second, the app also carries the authorize and token URLs (endpoints by hand). An app can be set for any server, not only one that needs it: connections then sign in through it instead of registering a client. Resolution order for a new connection matches native providers: workspace app, then org app, then platform app.

Requires credentials:read (get status) or credentials:write (create or update). Who may manage an app depends on manage_scopes in the status response (workspace admin, org admin from the org workspace, or platform operator).

Get MCP OAuth app status

GET /credentials/mcp/app?server_url={url}

Returns how connections to that MCP server sign in, for connect and admin UIs.

Response (MCPOAuthAppStatus):

Each app in app / apps (MCPOAuthAppDTO) includes client_id, has_secret, scope, status, and fields (values for app_fields). Secrets are never returned.

1curl "https://api.inference.sh/credentials/mcp/app?server_url=https%3A%2F%2Fmcp.dev.azure.com%2Fcontoso" \2  -H "Authorization: Bearer inf_your_key"

Set MCP OAuth app

PUT /credentials/mcp/app

Body (MCPOAuthAppRequest):

Only keys declared by the active authorization server profile, and the endpoint keys below, are accepted. The profile validates field values (for example Entra tenant id format).

Endpoints by hand

For a server whose OAuth metadata is missing or wrong, put the authorization server's endpoints on the app. With both endpoints set, connecting skips discovery and signs in through them.

A key sent with an empty value clears it; a key left out keeps its stored value. Clearing both endpoints puts the server back on discovery.

1curl -X PUT https://api.inference.sh/credentials/mcp/app \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{5    "server_url": "https://mcp.example.com/mcp",6    "client_id": "your-client-id",7    "client_secret": "your-client-secret",8    "fields": {9      "authorization_endpoint": "https://auth.example.com/oauth/authorize",10      "token_endpoint": "https://auth.example.com/oauth/token",11      "scopes": "read write"12    }13  }'

Connections made this way send the client id and secret to the token URL with HTTP Basic auth, and use PKCE. They send no RFC 8707 resource parameter and don't check an iss on the redirect, since there is no discovered issuer to check against. The server URL still has to be the MCP endpoint: tools are listed and called there with the token.

Remove MCP OAuth app

DELETE /credentials/mcp/app?server_url={url}&scope={team|org|platform}

Removes the app for that host and scope. Refused while active logins still reference the app.

Vault keys for MCP apps use the MCP_ prefix: MCP_CLIENT_ID, MCP_CLIENT_SECRET, and MCP_<FIELD> for each entry in app_fields (for example MCP_TENANT_ID) and each endpoint by hand (MCP_AUTHORIZATION_ENDPOINT, MCP_TOKEN_ENDPOINT, MCP_SCOPES).

OAuth callback without an authorization code

POST /oauth-callback/notice

Public endpoint (no API key). The web app's MCP OAuth callback uses this when the redirect carries no code — typically an error from the authorization server or a Microsoft admin consent landing that approves the app without connecting a user.

Body (OAuthCallbackNoticeRequest):

Response (OAuthCallbackNotice):

Set default account

PUT /credentials/{provider}/default?identifier={account_id_or_label}

Makes one login the default for its owner and provider. Other logins for the same provider stay connected with is_primary: false. Requires credentials:write and permission to manage the login (same as disconnect).

1curl -X PUT 'https://api.inference.sh/credentials/google/default?identifier=user%40company.com' \2  -H "Authorization: Bearer inf_your_key"

Response: the updated CredentialDTO with is_primary: true.

identifier is required. Omitting it returns a validation error.

Add OAuth scopes

POST /credentials/{provider}/scopes

Request additional scopes for an existing OAuth credential (incremental authorization). Optional identifier query parameter selects which account to extend (same as GET /credentials/{provider}); omit it to use the default login.

1{2  "scopes": ["https://www.googleapis.com/auth/drive.readonly"]3}

Response (same shape as Connect a credential):

1{2  "auth_url": "https://accounts.google.com/o/oauth2/v2/auth?...",3  "state": "st_abc123",4  "code_verifier": ""5}

Redirect the user to auth_url to approve the new scopes, then complete the flow with POST /credentials/oauth/complete (or your app's OAuth callback handler). Omit code_verifier when the API returned a non-empty value from connect or add-scopes — it is stored with the state challenge.

The authorize URL and the OAuth complete use the OAuth app that issued the login (app_credential_id), not whichever app a new connect would pick today, so token refresh stays on the client that issued the refresh token. A login saved before apps were recorded uses the app a new connect would take. If the issuing app row was deleted, add scopes answers 400 validation_error (the {provider} app this login was made through is gone; connect again).

The requested scopes are held to that app's allowed scopes: a scope the platform's client is approved for does not help when your workspace's app issued the login, and the other way round.

Incremental vs full re-authorization

Providers that support incremental authorization (for example google, microsoft, slack, salesforce, discord) return a consent URL that adds only the requested scopes. Existing grants are preserved.

Providers that do not support incremental auth (for example x) fall back to a full re-authorization URL that includes all existing scopes plus the new ones. The user must approve the combined scope list again.

Account pre-selection (login_hint)

When the credential has an account_identifier (email or username from the original connect), add-scopes auth_url values for Google and Microsoft include login_hint set to that identifier. The provider can skip the account chooser and go straight to consent for the same account. Custom OAuth auth providers can set account_hint_param (for example login_hint) to get the same behavior.

login_hint is not sent on the initial POST /credentials connect URL, only when re-authorizing for more scopes. It is omitted when account_identifier is empty — which is why OAuth complete refuses to save a login when the scheme expects an account id but the provider did not supply one (see Account identity on OAuth complete). A login saved during a temporary lookup outage gets account_identifier once it is next used, so a later add-scopes round trip can send login_hint.

Change connection scope

PUT /credentials/{provider}/scope

Rescopes an existing connection in place — same credential row and tokens, new owner level. Requires credentials:write. The same access rules apply as on connect: you must be allowed to use the connection at its current scope, and you must meet the admin requirements for the target scope (team needs workspace admin, org needs org admin, and so on).

Body:

1{2  "scope": "team"3}

MCP connections: Pass identifier as a query parameter with the MCP server_url (same as Disconnect):

1curl -X PUT 'https://api.inference.sh/credentials/mcp/scope?identifier=https%3A%2F%2Fmcp.linear.app%2Fsse' \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{"scope":"team"}'

Rules:

• Only the member who connected a row may narrow a shared connection to user (personal). A workspace admin cannot re-scope someone else's team connection to their own user row (403 forbidden).
• A member without workspace admin cannot widen a personal connection to team.
• When the workspace already has a shared connection for the same provider account, rescoping your personal row to that level returns 409 conflict — disconnect the duplicate or pick a different target scope.
• Call from the workspace that owns the connection. From any other workspace the API returns 400 validation_error.
• The credential's default vault membership is updated to match the new scope.

Response: CredentialDTO for the updated connection.

Disconnect

DELETE /credentials/{provider}

Revokes tokens with the provider when supported, then soft-deletes the workspace's connection for that provider. Vault membership links for the credential are removed as well. Apps that require the credential will fail until it is reconnected.

When the disconnected login was the default (is_primary: true), the owner's oldest remaining login for that provider becomes the new default.

An optional identifier query parameter selects one connection by account_id or account_identifier. belt mcp disconnect uses it with the MCP server URL (the stable id for MCP logins):

1curl -X DELETE 'https://api.inference.sh/credentials/mcp?identifier=https%3A%2F%2Fmcp.linear.app%2Fsse' \2  -H "Authorization: Bearer inf_your_key"

With identifier, the API walks the same ladder as a lookup without one, matching the named account on each rung (see Multiple accounts per provider). Platform-scope logins are on that ladder only in the platform workspace.

CLI equivalent: belt credentials disconnect <provider> (for example belt credentials disconnect google or belt credentials disconnect google-sa).

Check requirements (pre-flight)

POST /credentials/check

Validate secrets and credentials before calling POST /run. Returns 200 with a structured result (not HTTP 412):

1{2  "secrets": [3    { "key": "OPENAI_API_KEY", "optional": false }4  ],5  "credentials": [6    { "key": "google.sheets", "optional": false }7  ]8}

Response:

1{2  "satisfied": false,3  "errors": [4    {5      "type": "secret",6      "key": "OPENAI_API_KEY",7      "message": "Missing secret: OPENAI_API_KEY",8      "action": { "type": "add_secret" }9    },10    {11      "type": "credential",12      "key": "google.sheets",13      "message": "connect Google Account to use this app",14      "action": {15        "type": "connect",16        "provider": "google",17        "provider_name": "Google Account",18        "scopes": ["https://www.googleapis.com/auth/spreadsheets"],19        "scope_descriptions": {20          "https://www.googleapis.com/auth/spreadsheets": "View and manage your spreadsheets"21        }22      }23    },24    {25      "type": "scope",26      "key": "google.sheets",27      "message": "Google Account connected but missing permissions: [https://www.googleapis.com/auth/spreadsheets]",28      "action": {29        "type": "add_scopes",30        "provider": "google",31        "provider_name": "Google Account",32        "scopes": ["https://www.googleapis.com/auth/spreadsheets"],33        "scope_descriptions": {34          "https://www.googleapis.com/auth/spreadsheets": "View and manage your spreadsheets"35        }36      }37    }38  ]39}

Each errors[] entry has type (secret, credential, or scope), key, message, and optional action (add_secret, connect, add_scopes).

Use provider (not provider_name) when calling POST /credentials or belt credentials connect. Use provider_name or message when showing setup prompts to end users.

For dashboard links, resolve {slug} from GET /credentials/configs — match provider and the capability type from GET /credentials/capabilities. For most providers slug equals provider; Google OAuth uses google, the Sheets/Docs/Drive service account uses google-sa, and GCP WIF uses gcp. → Credentials overview — detail page

When requirements are missing at run time, POST /run and POST /apps/run return 412 with a plain JSON body (not problem+json):

1{2  "satisfied": false,3  "errors": [ /* the same RequirementError objects as check */ ]4}

Other routes refused for incomplete setup (for example an agent message whose run needs a credential) answer 412 application/problem+json with code requirements_not_met; the same list is the problem's top-level errors member and is repeated under meta.errors. Use check when you want the list without submitting a task (it always answers 200).

CLI: belt app run and belt agent run catch 412 responses and print categorized hints — belt secrets set for missing secrets, belt credentials connect for OAuth providers, belt mcp connect for MCP requirements, or connect at: https://app.inference.sh/vaults when the requirement names no provider. Next to belt credentials connect <provider> the CLI also prints or: https://app.inference.sh/vaults/<provider>.

→ Secrets · CLI setup · Troubleshooting

MCP tool proxy

After connecting an MCP server (provider: "mcp"), call tools over HTTP:

{slug} is the MCP server slug (for example linear from the connector directory). Tool calls are recorded in your workspace's credential history.

CLI equivalent: belt mcp tools <slug> and belt mcp run <slug>:<tool>.

→ Connectors browsing · MCP server

JavaScript SDK

1import { inference } from '@inferencesh/sdk';23const client = inference({ apiKey: 'inf_your_key' });45const caps = await client.credentials.getCapabilities();6const { auth_url } = await client.credentials.connect({7  provider: 'google',8  type: 'oauth',9  scopes: ['https://www.googleapis.com/auth/spreadsheets'],10});11await client.credentials.checkRequirements({12  secrets: [{ key: 'OPENAI_API_KEY' }],13  credentials: [{ key: 'google.sheets' }],14});

→ SDK overview — client.credentials namespace

Related

• REST overview — authentication and response format
• Entitlements — connector limits on your plan
• Agent connector tools — use credentials from agents