Skip to main content
Reference for every authentication method RubixKube supports on integrations. Pick the section for the scheme you need, or see the table below for a quick overview.

​
Quick overview

MethodBest forSecret storage
API key or Bearer tokenSimple internal APIs, machine-to-machineVault, per integration
OAuth 2.0 Authorisation CodeUser-scoped actions (Slack, Linear, Notion)Vault with automated refresh
OAuth 2.0 Client CredentialsService-to-service with OAuthVault with automated refresh
mTLSPrivate APIs with network-level trustVault with client certificate
HMAC signed requestsWebhooks, event ingestionVault with shared secret
JWT in headerAPIs that mint short-lived tokensVault with signing key, tokens minted just-in-time
All secrets live in the workspace secret vault, encrypted at rest, scoped per integration, and never visible in agent prompts or logs.

​
API key or Bearer token

The simplest option. A static credential passed in a header or query parameter.

When to use

Internal tools, machine-to-machine calls, read-only APIs.

When to avoid

User-scoped actions, anything that needs per-user authorisation, anywhere a key rotation cadence is hard to run.
Configure in Integrations → [your integration] → Auth. Set the header name (default Authorization: Bearer <token>) or the query parameter if the API is quirky.

​
OAuth 2.0 (Authorisation Code)

The standard flow for user-scoped integrations. RubixKube handles the redirect handshake and refresh cycle.
1

Register an OAuth app

On the upstream tool (Slack, Linear, Atlassian, etc.), create an OAuth application. Set the redirect URL to https://api.rubixkube.ai/oauth/callback.
2

Add client credentials to RubixKube

Paste the client ID and client secret into the integration’s Auth tab.
3

Authorise

Click Connect, sign in on the upstream tool, and approve the scopes RubixKube requests. The refresh token is stored in the vault.
4

Scope narrowly

Request the smallest scope that works. If the upstream offers a dedicated “read” scope, pick that over “read and write”.
Refresh tokens rotate automatically. If an upstream invalidates the token (common after 90 days of inactivity), the integration card flags Reauthorise needed.

​
OAuth 2.0 (Client Credentials)

Service-to-service with OAuth. No user interaction. Supply the client ID, client secret, and token endpoint URL. Optional scope and audience claims. RubixKube fetches tokens just-in-time and caches them for their lifetime.

​
mTLS

For private APIs where you want network-level trust.
1

Obtain a client certificate

Issue a client cert from your internal CA, scoped to the RubixKube Cloud egress identity.
2

Upload to the vault

In the integration’s Auth tab, upload the certificate (PEM) and private key. Configure the expected server certificate chain if needed.
3

Configure rotation

Set a rotation reminder. RubixKube notifies the workspace admin 14 days before the cert expires.

​
HMAC signed requests

Common for webhook-style APIs. RubixKube signs each outbound call with a shared secret using HMAC-SHA256 (or SHA512). Configuration:
  • Shared secret in the vault.
  • Signed header name (default X-Signature).
  • Optional timestamp header for replay protection.

​
JWT in header

APIs that require a short-lived JWT minted per request. RubixKube supports:
  • HS256 / HS384 / HS512 with a shared secret.
  • RS256 / RS384 / RS512 with an RSA private key.
  • ES256 / ES384 with an EC private key.
Claims (issuer, audience, subject, expiry, custom) are configurable per integration. Tokens are minted just-in-time and never persisted beyond their expiry.

​
Secret rotation

All secret types support rotation without downtime.
Upload the new secret alongside the old one. RubixKube switches to the new secret on the next outbound call and retires the old one after a grace window.
Configure a rotation cadence per integration. The workspace admin gets notified when a rotation is due.
Emergency rotation revokes the old secret immediately. Any in-flight calls fail, future calls use the new secret.

​
Audit

Every auth event is audited: token issued, token refreshed, reauthorise required, rotation completed, cert expiring. Audit entries are immutable and retained per your plan.

​
Troubleshooting

The redirect URL on the upstream app does not match https://api.rubixkube.ai/oauth/callback exactly. Check for trailing slashes or protocol mismatches.
Most common cause is cert chain mismatch. Upload the intermediate certs into the vault alongside the client cert. Check SNI if the upstream uses multiple virtual hosts.
Check the header name and the signing algorithm (usually SHA256). Some APIs include the request body hash, others include a timestamp. Match the upstream’s canonicalisation exactly.

Custom REST Integrations

Where most auth configuration lives in practice.

Custom MCP Servers

Auth for internal MCP servers works the same way.