Credentials

Introduction

Credentials are upstream API secrets for managed sources. You enter a secret once. The dashboard never keeps it, not even a hash, and never echoes it back. swarmvia encrypts it on save and decrypts it only inside an isolated sandbox to reach your origin. Attach one credential to any number of managed sources; rotating it updates every source that uses it.

Manage credentials under Credentials in the dashboard.

Create a credential

Open Credentials → Add credential.
Name it and choose an auth method (bearer, basic, API key, OAuth 1.0, OAuth2 client-credentials, or OAuth2 refresh token).
Enter the secret fields and save. An OAuth 2 credential is checked at its token endpoint before it is stored. A rejection names the error (invalid_client, invalid_scope, and so on) and nothing is saved.

Attach to a source

On a managed source's Settings, select the credential. It applies to new requests within a few seconds.

Pass-through sources do not use credentials. Callers supply upstream auth on each request.

OAuth 2.0 client credentials

Choose how swarmvia authenticates at the token URL:

Client secret — HTTP Basic with client id and secret (default).
Private key JWT — swarmvia signs a short-lived JWT (private_key_jwt) and posts it as client_assertion. Paste a private key, or use Generate certificate to mint a self-signed public certificate. The PS* and RS* algorithms use a 4096-bit RSA key; ES256, ES384, and ES512 use EC P-256, P-384, and P-521 keys. The form names that type before you download it. Download the certificate (and the private key, if you want your own copy) as PEM files. Upload the certificate to the identity provider when it asks for one. After mapping, paste that certificate id into Certificate ID (kid). Algorithm defaults to PS256; every PS*, RS*, and ES* variant is available. Providers differ: NetSuite accepts the PS* and ES* algorithms and rejects RS*, so check the provider's documented list.

The private key is sealed in swarmvia like any other secret. The public certificate is shown once for download and is not stored.

OAuth 2.0 refresh token

Use this when the origin issues access tokens from a stored refresh token instead of a client-credentials grant. Amazon SP-API (Login with Amazon) is the usual case: one developer app, one refresh token sealed in swarmvia, many callers with access keys.

Set the token URL and the header the access token is attached as. For Amazon SP-API that is https://api.amazon.com/auth/o2/token and x-amz-access-token. swarmvia exchanges the refresh token, caches the access token, and attaches it as that header. Callers never see the refresh token or client secret.

See Front Amazon SP-API.

Connect

Use Connect when the provider hands out refresh tokens only through a sign-in (OAuth 2.0 authorization code), which is the case for GitHub, Linear, and Amazon SP-API seller authorization. Add an OAuth 2.0 refresh token credential and choose Connect, then pick a provider. An MCP server is not set up here: create an MCP source from its URL, and the source owns its credential.

Provider	What you enter
Amazon Selling Partner API	Seller Central store, SP-API application ID, LWA client ID and secret. See Front Amazon SP-API.
GitHub / Linear	Your OAuth app's client ID and secret, and scopes.
Custom OAuth provider	Authorization and token endpoints, client ID, optional secret (leave empty for a public client), scopes, and an optional resource indicator.

Register the redirect URI the form shows with the provider, then choose Save and connect. You sign in at the provider and land back on Credentials with the credential connected. PKCE (S256) is used whenever the provider supports it, and MCP servers get their resource indicator on every token request.

The client secret and the tokens the provider issues are sealed at the edge. The dashboard only keeps public settings (endpoints, client ID, scopes) and who connected which account.

The row names the next sign-in from the connection. Connect until someone has signed in. Reconnect once that grant exists, including when the provider rejects it. A source's reconnect_url goes straight there.

Per-member credentials

Check Each member connects their own account when the provider should see the person behind each call, for example so GitHub or Linear apply that person's permissions. The credential then holds only your OAuth app. Every member chooses Connect on the credential row, and swarmvia calls the provider with the connection that belongs to whoever's key made the request.

Calls need a key that acts for a member (see Keys that act for a member). A machine key gets 403 credential_requires_member_key.
A member who has not connected gets 424 credential_needs_reauthorization (reason not_connected). The reconnect_url takes them straight to connecting their own account.
Members can disconnect themselves; owners and admins see every member's connection and can disconnect anyone.
Removing a member from the org disconnects them.
If a provider rejects one member's connection, only that member's calls fail, and that member gets the email. Their row says Reconnect.
There is no Rotate on a Connect credential, including one that is not connected yet. Signing in replaces that member's grant. Other members' connections stay as they are.

Rotate

Rotate is for a pasted secret (bearer token, API key, or a refresh token you pasted). Sources that reference the credential pick up the new secret within a few seconds without changing access keys or client config. A Connect credential is not rotated here: use Connect or Reconnect on the row.

If the provider issues a new refresh token each time it refreshes (refresh-token rotation), swarmvia stores the new one before using the access token. Every source that shares the credential refreshes through the same stored copy, so they never invalidate each other's refresh token.

Credential health

OAuth 2.0 credentials show a status on the Credentials page once a source has used them:

Status	Meaning	What callers get
Active	The last token request succeeded.	Normal responses.
Needs reauthorization	The token endpoint rejected the credential itself, for example a revoked refresh token (`invalid_grant`) or a wrong client secret (`invalid_client`).	`424 credential_needs_reauthorization` with a `reconnect_url`.
Token endpoint down	The token endpoint failed (5xx, throttled, or unreachable).	`503 credential_unavailable` with `Retry-After`. The same answer, with reason `vault_error`, when swarmvia briefly cannot read the stored credential.

A rejected credential is not retried against the provider on every request. swarmvia checks again every five minutes, and immediately after you rotate it. During an outage it backs off from one second up to a minute.

The org owner gets one email when a credential moves to Needs reauthorization. The source page lists it as an action item. The reconnect_url in the error sends a signed-in member to sign in again for a Connect credential, or to the rotate dialog for a pasted secret. Members who cannot manage a shared credential land on the source's Access tab.

Requests that fail this way are logged with the outcome credential error, separate from upstream error, so a dead credential never looks like the origin being down.